diff --git a/Source/ThirdParty/SDL/SDL3/SDL.h b/Source/ThirdParty/SDL/SDL3/SDL.h index c7fa36677..0b4388eb5 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL.h +++ b/Source/ThirdParty/SDL/SDL3/SDL.h @@ -20,9 +20,12 @@ */ /** - * \file SDL.h + * Main include header for the SDL library, version 3.1.7 * - * Main include header for the SDL library, version 3.1.7 + * 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 @@ -77,6 +81,7 @@ #include #include #include +#include #include #include #include diff --git a/Source/ThirdParty/SDL/SDL3/SDL_assert.h b/Source/ThirdParty/SDL/SDL3/SDL_assert.h index d09e46c0f..aeaa62239 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_assert.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_assert.h @@ -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_ @@ -151,14 +156,37 @@ extern "C" { #define SDL_TriggerBreakpoint() #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.1.3. + */ +#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.1.3. + */ #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.1.3. + */ #define SDL_LINE __LINE__ /* @@ -176,14 +204,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.1.3. + */ +#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.1.3. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -232,7 +296,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. @@ -248,23 +312,49 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * 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.1.3. + */ #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.1.3. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h b/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h new file mode 100644 index 000000000..3c983913d --- /dev/null +++ b/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2024 Sam Lantinga + + 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.0.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.0.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.0.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_CANCELLED /**< request was cancelled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.0.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.0.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/Source/ThirdParty/SDL/SDL3/SDL_atomic.h b/Source/ThirdParty/SDL/SDL3/SDL_atomic.h index 14ba31fad..be4c39882 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_atomic.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_atomic.h @@ -155,6 +155,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * \since This macro is available since SDL 3.1.3. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -171,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.1.3. + * + * \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.1.3. + * + * \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. @@ -191,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.1.3. + * \since This macro is available since SDL 3.1.3. + * + * \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.1.3. + * \since This macro is available since SDL 3.1.3. * - * \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__) @@ -284,6 +344,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * \since This macro is available since SDL 3.1.3. */ #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__) diff --git a/Source/ThirdParty/SDL/SDL3/SDL_audio.h b/Source/ThirdParty/SDL/SDL3/SDL_audio.h index f178853bd..d9fa496df 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_audio.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_audio.h @@ -141,14 +141,68 @@ 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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ +#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. @@ -399,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. * @@ -453,7 +499,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. @@ -682,11 +727,11 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic /** * Determine if an audio device is physical (instead of logical). * - * An SDL_AudioDeviceID that represents physical hardare 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. + * 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 diff --git a/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h b/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h index acf99284c..bfb1c2cc2 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h @@ -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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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)) diff --git a/Source/ThirdParty/SDL/SDL3/SDL_bits.h b/Source/ThirdParty/SDL/SDL3/SDL_bits.h index cabf92d17..71f356ce6 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_bits.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_bits.h @@ -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 = \ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_blendmode.h b/Source/ThirdParty/SDL/SDL3/SDL_blendmode.h index 0998c1a1e..b9dbbe4b3 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_blendmode.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_blendmode.h @@ -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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_camera.h b/Source/ThirdParty/SDL/SDL3/SDL_camera.h index 5ac47ea6d..c3611f072 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_camera.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_camera.h @@ -29,6 +29,25 @@ * 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, @@ -40,10 +59,10 @@ * * 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 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. + * 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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h b/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h index b23bdb786..448cb4a53 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h @@ -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_ @@ -49,7 +94,7 @@ extern "C" { * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -68,7 +113,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -82,7 +127,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); * * \returns true if the clipboard has text, or false if it does not. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -98,7 +143,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -117,7 +162,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -132,7 +177,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * * \returns true if the primary selection has text, or false if it does not. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -181,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. @@ -199,7 +244,7 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -215,7 +260,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -235,7 +280,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); * for more information. This should be freed with SDL_free() when it * is no longer needed. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -251,7 +296,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, s * \returns true if there exists data in clipboard for the provided mime type, * false if it does not. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -269,7 +314,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * diff --git a/Source/ThirdParty/SDL/SDL3/SDL_close_code.h b/Source/ThirdParty/SDL/SDL3/SDL_close_code.h index fa4d3d17b..aba9066cb 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_close_code.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_close_code.h @@ -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/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h b/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h index 8d47d92d3..eca703aa1 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h @@ -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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_dialog.h b/Source/ThirdParty/SDL/SDL3/SDL_dialog.h index 21b022c58..9d66573f6 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_dialog.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_dialog.h @@ -23,6 +23,15 @@ * # 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_ @@ -30,6 +39,7 @@ #include #include +#include #include #include @@ -55,6 +65,7 @@ extern "C" { * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef struct SDL_DialogFileFilter { @@ -93,14 +104,13 @@ typedef struct 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. * @@ -127,19 +137,25 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * Not all platforms support this option. * \param filters a list of filters, may be NULL. Not all platforms support * this option, and platforms that do support it may allow the - * user to ignore the filters. + * 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 allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * + * \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.1.3. * * \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, bool allow_many); @@ -147,8 +163,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * 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,25 +188,29 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * Not all platforms support this option. * \param filters a list of filters, may be NULL. Not all platforms support * this option, and platforms that do support it may allow the - * user to ignore the filters. + * 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. * + * \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.1.3. * * \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. * @@ -222,14 +240,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * + * \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.1.3. * * \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, 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.1.3. + * + * \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 } diff --git a/Source/ThirdParty/SDL/SDL3/SDL_endian.h b/Source/ThirdParty/SDL/SDL3/SDL_endian.h index 888180443..bf1dd206d 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_endian.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_endian.h @@ -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.1.3. + * + * \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.1.3. + * + * \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.1.3. + * + * \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.1.3. + * + * \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. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_error.h b/Source/ThirdParty/SDL/SDL3/SDL_error.h index 6818e411a..c96d1511a 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_error.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_error.h @@ -178,8 +178,43 @@ extern SDL_DECLSPEC 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.1.3. + */ #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.1.3. + */ #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + /* @} *//* Internal error functions */ /* Ends C function definitions when using C++ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_events.h b/Source/ThirdParty/SDL/SDL3/SDL_events.h index aa1691b95..2850b7639 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_events.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_events.h @@ -23,6 +23,30 @@ * # 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_WaitEvents() 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_ @@ -334,8 +358,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 */ - bool down; /**< true if the key is pressed */ - bool repeat; /**< true 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; /** @@ -422,7 +446,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 */ @@ -441,9 +465,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 */ - bool down; /**< true if the button is pressed */ + 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 */ @@ -461,7 +485,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 */ @@ -773,7 +797,7 @@ 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; @@ -793,7 +817,7 @@ 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 coordinate, relative to window */ @@ -1034,9 +1058,7 @@ 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. * - * \threadsafety 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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1234,9 +1256,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * the queue, or NULL. * \returns true if this got an event or false if there are none available. * - * \threadsafety 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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1260,9 +1280,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); * \returns true on success or false if there was an error while waiting for * events; call SDL_GetError() for more information. * - * \threadsafety 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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1292,9 +1310,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); * \returns true if this got an event or false if the timeout elapsed without * any events available. * - * \threadsafety 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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * diff --git a/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h b/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h index af3eae2ac..13234afde 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h @@ -166,29 +166,17 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * typedef enum SDL_Folder { 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; /** @@ -219,6 +207,17 @@ 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.1.3. + * + * \sa SDL_PathInfo + */ typedef enum SDL_PathType { SDL_PATHTYPE_NONE, /**< path does not exist */ @@ -227,6 +226,14 @@ 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.1.3. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ typedef struct SDL_PathInfo { SDL_PathType type; /**< the path type */ @@ -237,7 +244,7 @@ typedef struct SDL_PathInfo } SDL_PathInfo; /** - * Flags for path matching + * Flags for path matching. * * \since This datatype is available since SDL 3.1.3. * diff --git a/Source/ThirdParty/SDL/SDL3/SDL_gpu.h b/Source/ThirdParty/SDL/SDL3/SDL_gpu.h index 0e7c9fd84..6d8b90e7b 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_gpu.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_gpu.h @@ -25,7 +25,7 @@ * # CategoryGPU * * 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 + * 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: @@ -56,7 +56,7 @@ * 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_AcquireGPUSwapchainTexture() to render to the window. + * 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 @@ -129,7 +129,7 @@ * * 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_gpu_shadercross](https://github.com/libsdl-org/SDL_gpu_shadercross) + * [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 @@ -159,6 +159,24 @@ * 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. + * + * ## 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 */ #ifndef SDL_gpu_h_ @@ -1068,32 +1086,26 @@ typedef enum SDL_GPUSamplerAddressMode * Specifies the timing that will be used to present swapchain textures to the * OS. * - * Note that this value affects the behavior of - * SDL_AcquireGPUSwapchainTexture. VSYNC mode will always be supported. - * IMMEDIATE and MAILBOX modes may not be supported on certain systems. + * 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. When using - * this present mode, AcquireGPUSwapchainTexture will block if too many - * frames are in flight. + * presentation. Disallows tearing at the cost of visual latency. * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may - * occur. When using this mode, AcquireGPUSwapchainTexture will fill the - * swapchain texture pointer with NULL if too many frames are in flight. + * 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. When using - * this mode, AcquireGPUSwapchainTexture will fill the swapchain texture - * pointer with NULL if too many frames are in flight. + * new image. Similar to VSYNC, but with reduced visual latency. * * \since This enum is available since SDL 3.1.3 * * \sa SDL_SetGPUSwapchainParameters * \sa SDL_WindowSupportsGPUPresentMode - * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUPresentMode { @@ -1125,7 +1137,7 @@ typedef enum SDL_GPUPresentMode * * \sa SDL_SetGPUSwapchainParameters * \sa SDL_WindowSupportsGPUSwapchainComposition - * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUSwapchainComposition { @@ -1510,13 +1522,6 @@ typedef struct SDL_GPUTextureCreateInfo 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. * @@ -1526,6 +1531,7 @@ typedef struct SDL_GPUTextureCreateInfo * \since This struct is available since SDL 3.1.3 * * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags */ typedef struct SDL_GPUBufferCreateInfo { @@ -1659,6 +1665,12 @@ typedef struct SDL_GPUGraphicsPipelineTargetInfo * \since This struct is available since SDL 3.1.3 * * \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 { @@ -2084,23 +2096,23 @@ extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUD * * - 0: Sampled textures, followed by read-only storage textures, followed by * read-only storage buffers - * - 1: Write-only storage textures, followed by write-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers * - 2: Uniform buffers * * 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): Write-only storage textures, followed by write-only + * - (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 write-only storage buffers, - * followed by write-only storage buffers + * - [[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 write-only storage textures + * followed by read-write storage textures * * \param device a GPU Context. * \param createinfo a struct describing the state of the compute pipeline to @@ -2203,6 +2215,15 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * [[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(). + * * \param device a GPU Context. * \param createinfo a struct describing the state of the shader to create. * \returns a shader object on success, or NULL on failure; call @@ -2230,6 +2251,31 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. 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_GPU_CREATETEXTURE_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_CREATETEXTURE_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_CREATETEXTURE_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_CREATETEXTURE_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_CREATETEXTURE_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_CREATETEXTURE_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. + * * \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 @@ -2252,6 +2298,14 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, const SDL_GPUTextureCreateInfo *createinfo); +#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" + + /** * Creates a buffer object to be used in graphics or compute workflows. * @@ -2261,6 +2315,11 @@ 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. * + * 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/) + * . + * * \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 @@ -3442,9 +3501,12 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( * \returns true on success, or 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.1.3. * - * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_ReleaseWindowFromGPUDevice * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition @@ -3496,6 +3558,35 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( 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. * @@ -3517,20 +3608,21 @@ 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. The swapchain texture handle can be filled in - * with NULL under certain conditions. This is not necessarily an error. If - * this function returns false then there is an error. + * buffer used to acquire it. + * + * 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. * - * When using SDL_GPU_PRESENTMODE_VSYNC, this function will block if too many - * frames are in flight. Otherwise, this function will fill the swapchain - * texture handle with NULL if too many frames are in flight. The best - * practice is to call SDL_CancelGPUCommandBuffer if the swapchain texture - * handle is NULL to avoid enqueuing needless work on the GPU. - * * \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 @@ -3542,14 +3634,19 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma * \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.1.3. * - * \sa SDL_GPUPresentMode * \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 bool SDLCALL SDL_AcquireGPUSwapchainTexture( SDL_GPUCommandBuffer *command_buffer, @@ -3558,6 +3655,72 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( 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. * @@ -3575,6 +3738,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( * \since This function is available since SDL 3.1.3. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ @@ -3600,6 +3764,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( * \since This function is available since SDL 3.1.3. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_ReleaseGPUFence @@ -3612,11 +3777,12 @@ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFe * * 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. It - * is an error to call this function after a swapchain texture has been - * acquired. + * 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 @@ -3624,6 +3790,7 @@ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFe * * \since This function is available since SDL 3.1.6. * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUCommandBuffer * \sa SDL_AcquireGPUSwapchainTexture */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_guid.h b/Source/ThirdParty/SDL/SDL3/SDL_guid.h index 7806d835c..2f464c675 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_guid.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_guid.h @@ -26,6 +26,8 @@ * * 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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_haptic.h b/Source/ThirdParty/SDL/SDL3/SDL_haptic.h index c123cd90c..533f3bcee 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_haptic.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_haptic.h @@ -299,12 +299,24 @@ typedef struct SDL_Haptic SDL_Haptic; #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * * \since This macro is available since SDL 3.1.3. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** diff --git a/Source/ThirdParty/SDL/SDL3/SDL_hints.h b/Source/ThirdParty/SDL/SDL3/SDL_hints.h index 97b859626..1e03207d7 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_hints.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_hints.h @@ -216,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.1.3. + * + * \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.1.7. + * + * \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.1.7. + * + * \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. * @@ -1327,7 +1369,7 @@ 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.1.3. */ @@ -1344,7 +1386,7 @@ 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.1.3. */ @@ -1361,7 +1403,7 @@ 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.1.3. */ @@ -1399,7 +1441,7 @@ 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.1.3. */ @@ -1435,7 +1477,7 @@ 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.1.3. */ @@ -1452,7 +1494,7 @@ 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.1.3. */ @@ -1474,7 +1516,7 @@ 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.1.3. */ @@ -1491,7 +1533,7 @@ 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.1.3. */ @@ -1508,7 +1550,7 @@ 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.1.3. */ @@ -1566,7 +1608,7 @@ 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.1.3. */ @@ -1621,7 +1663,7 @@ 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.1.3. */ @@ -1653,7 +1695,7 @@ 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.1.3. */ @@ -1689,7 +1731,7 @@ 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.1.3. */ @@ -1717,7 +1759,7 @@ 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.1.3. */ @@ -1785,7 +1827,7 @@ extern "C" { * 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.1.3. */ @@ -1818,7 +1860,7 @@ 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.1.3. */ @@ -1835,7 +1877,7 @@ 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.1.3. */ @@ -1867,7 +1909,7 @@ 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.1.3. */ @@ -1884,7 +1926,7 @@ 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.1.3. */ @@ -2490,21 +2532,6 @@ extern "C" { */ #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.1.3. - */ -#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. @@ -2572,23 +2599,6 @@ extern "C" { */ #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 milliseconds 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.1.3. - */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" - /** * A variable controlling whether mouse events should generate synthetic touch * events. @@ -2862,6 +2872,7 @@ extern "C" { * - "opengles" * - "metal" * - "vulkan" + * - "gpu" * - "software" * * The default varies by platform, but it's the first one in the list that is @@ -4010,6 +4021,15 @@ extern "C" { * \since This hint is available since SDL 3.1.3. */ #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.1.3. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** diff --git a/Source/ThirdParty/SDL/SDL3/SDL_init.h b/Source/ThirdParty/SDL/SDL3/SDL_init.h index 3d518e668..10b04b4e9 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_init.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_init.h @@ -78,7 +78,7 @@ extern "C" { typedef Uint32 SDL_InitFlags; #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` */ @@ -113,11 +113,71 @@ 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.1.3. + */ 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.1.3. + */ typedef SDL_AppResult (SDLCALL *SDL_AppIterate_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.1.3. + */ 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.1.3. + */ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. * @@ -139,7 +199,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); * - `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 @@ -239,6 +299,63 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); */ 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.1.8. + * + * \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. * diff --git a/Source/ThirdParty/SDL/SDL3/SDL_intrin.h b/Source/ThirdParty/SDL/SDL3/SDL_intrin.h index efba11d53..457328faf 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_intrin.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_intrin.h @@ -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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + */ +#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 3.1.3. + */ +#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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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 3.1.3. + * + * \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.1.3. + * + * \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.1.3. + */ +#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/Source/ThirdParty/SDL/SDL3/SDL_joystick.h b/Source/ThirdParty/SDL/SDL3/SDL_joystick.h index 44770972c..580000206 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_joystick.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_joystick.h @@ -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 diff --git a/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h b/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h index 5bae001e0..f6505d19e 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h @@ -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_ @@ -61,6 +66,8 @@ typedef Uint32 SDL_KeyboardID; * * \returns true if a keyboard is connected, false otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyboards @@ -81,6 +88,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); * 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.1.3. * * \sa SDL_GetKeyboardNameForID @@ -97,6 +106,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyboards @@ -108,6 +119,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID * * \returns the window with keyboard focus. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); @@ -136,6 +149,8 @@ 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. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_PumpEvents @@ -148,6 +163,8 @@ extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); * * This function will generate key up events for all pressed keys. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyboardState @@ -160,6 +177,8 @@ 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. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyboardState @@ -180,6 +199,8 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * * \param modstate the desired SDL_Keymod for the keyboard. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetModState @@ -201,6 +222,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyName @@ -220,6 +243,8 @@ 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. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyFromScancode @@ -237,6 +262,8 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \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.1.3. * * \sa SDL_GetScancodeName @@ -259,6 +286,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, cons * \returns a pointer to the name for the scancode. If the scancode doesn't * have a name this function returns an empty string (""). * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetScancodeFromKey @@ -274,6 +303,8 @@ 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. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyFromName @@ -290,6 +321,8 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyFromName @@ -305,6 +338,8 @@ 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. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetKeyFromScancode @@ -330,6 +365,8 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * \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.1.3. * * \sa SDL_SetTextInputArea @@ -423,6 +460,8 @@ typedef enum SDL_Capitalization * \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.1.3. * * \sa SDL_SetTextInputArea @@ -444,6 +483,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *wi * \param window the window to check. * \returns true if text input events are enabled else false. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_StartTextInput @@ -460,6 +501,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *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.1.3. * * \sa SDL_StartTextInput @@ -473,6 +516,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *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.1.3. * * \sa SDL_StartTextInput @@ -494,6 +539,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *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.1.3. * * \sa SDL_GetTextInputArea @@ -514,6 +561,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const * \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.1.3. * * \sa SDL_SetTextInputArea @@ -526,6 +575,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Re * \returns true if the platform has some screen keyboard support or false if * not. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_StartTextInput @@ -539,6 +590,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); * \param window the window for which screen keyboard should be queried. * \returns true if screen keyboard is shown or false if not. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_HasScreenKeyboardSupport diff --git a/Source/ThirdParty/SDL/SDL3/SDL_keycode.h b/Source/ThirdParty/SDL/SDL3/SDL_keycode.h index 77968bd09..3d7723d13 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_keycode.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_keycode.h @@ -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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_loadso.h b/Source/ThirdParty/SDL/SDL3/SDL_loadso.h index 53c496711..027462fe5 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_loadso.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_loadso.h @@ -46,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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_locale.h b/Source/ThirdParty/SDL/SDL3/SDL_locale.h index 3042bd858..a5035830f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_locale.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_locale.h @@ -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 diff --git a/Source/ThirdParty/SDL/SDL3/SDL_main.h b/Source/ThirdParty/SDL/SDL3/SDL_main.h index 9b97abda6..b244af1cd 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_main.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_main.h @@ -28,13 +28,20 @@ * should look like this: * * ```c - * int main(int argc, char *argv[]) - * { - * } + * 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 @@ -48,6 +55,84 @@ #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.1.3. + */ +#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.1.3. + * + * \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.1.3. + */ +#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.1.3. + */ +#define SDL_MAIN_NEEDED + +#endif + #ifndef SDL_MAIN_HANDLED #if defined(SDL_PLATFORM_PRIVATE_MAIN) /* Private platforms may have their own ideas about entry points. */ @@ -134,17 +219,29 @@ */ #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 */ -#ifdef SDL_MAIN_EXPORTED + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a main entry point function as exported. + * + * 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. + * + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. + * + * \since This macro is available since SDL 3.1.3. + * + * \sa SDL_DECLSPEC + */ +#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 @@ -153,31 +250,6 @@ #define SDLMAIN_DECLSPEC #endif /* SDL_MAIN_EXPORTED */ -#ifdef SDL_WIKI_DOCUMENTATION_SECTION - -/** - * 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.1.3. - * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit - */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif - #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main #endif @@ -567,17 +639,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); #endif /* defined(SDL_PLATFORM_WINDOWS) */ -#ifdef SDL_PLATFORM_GDK - /** * Callback from the application to let the suspend continue. * + * 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.1.3. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); -#endif /* SDL_PLATFORM_GDK */ - #ifdef __cplusplus } #endif diff --git a/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h b/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h index e5560e388..761e6b887 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h @@ -131,18 +131,6 @@ /* end of SDL_PLATFORM_WINDOWS impls */ - #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 */ - #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/Source/ThirdParty/SDL/SDL3/SDL_mouse.h b/Source/ThirdParty/SDL/SDL3/SDL_mouse.h index 9068b3fab..e6c1ab60b 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_mouse.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_mouse.h @@ -139,6 +139,8 @@ typedef Uint32 SDL_MouseButtonFlags; * * \returns true if a mouse is connected, false otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetMice @@ -159,6 +161,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); * 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.1.3. * * \sa SDL_GetMouseNameForID @@ -175,6 +179,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetMice @@ -186,6 +192,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta * * \returns the window with mouse focus. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); @@ -214,6 +222,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); * \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.1.3. * * \sa SDL_GetGlobalMouseState @@ -248,6 +258,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, flo * \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.1.3. * * \sa SDL_CaptureMouse @@ -282,6 +294,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float * * \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.1.3. * * \sa SDL_GetMouseState @@ -304,6 +318,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_WarpMouseGlobal @@ -327,6 +343,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * 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.1.3. * * \sa SDL_WarpMouseInWindow @@ -348,6 +366,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * \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.1.3. * * \sa SDL_GetWindowRelativeMouseMode @@ -360,6 +380,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *wind * \param window the window to query. * \returns true if relative mode is enabled for a window or false otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowRelativeMouseMode @@ -406,6 +428,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *wind * \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.1.3. * * \sa SDL_GetGlobalMouseState @@ -447,6 +471,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); * \returns a new cursor with the specified parameters on success or NULL 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.1.3. * * \sa SDL_CreateColorCursor @@ -478,6 +504,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreateCursor @@ -496,6 +524,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_DestroyCursor @@ -514,6 +544,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * \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.1.3. * * \sa SDL_GetCursor @@ -528,6 +560,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); * * \returns the active cursor or NULL if there is no mouse. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetCursor @@ -543,6 +577,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); @@ -555,6 +591,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); * * \param cursor the cursor to free. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreateColorCursor @@ -569,6 +607,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); * \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.1.3. * * \sa SDL_CursorVisible @@ -582,6 +622,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); * \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.1.3. * * \sa SDL_CursorVisible @@ -595,6 +637,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); * \returns `true` if the cursor is being shown, or `false` if the cursor is * hidden. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_HideCursor diff --git a/Source/ThirdParty/SDL/SDL3/SDL_mutex.h b/Source/ThirdParty/SDL/SDL3/SDL_mutex.h index b3fddeebd..e21d3df1f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_mutex.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_mutex.h @@ -33,78 +33,225 @@ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) diff --git a/Source/ThirdParty/SDL/SDL3/SDL_pixels.h b/Source/ThirdParty/SDL/SDL3/SDL_pixels.h index eb6ff5018..1f4f97562 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_pixels.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_pixels.h @@ -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_ @@ -161,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.1.3. + */ #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.1.3. + */ #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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + * + * \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.1.3. + * + * \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.1.3. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -187,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.1.3. + */ #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.1.3. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -201,16 +426,55 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) +/** + * 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.1.3. + */ #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.1.3. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) +/** + * 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.1.3. + */ #define SDL_ISPIXELFORMAT_ALPHA(format) \ ((SDL_ISPIXELFORMAT_PACKED(format) && \ ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ @@ -223,8 +487,23 @@ typedef enum SDL_PackedLayout (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) -/* 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 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.1.3. + */ +#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() */ @@ -419,30 +698,6 @@ typedef enum SDL_PixelFormat #endif } SDL_PixelFormat; -/** - * 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. * @@ -563,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.1.3. + */ #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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h b/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h index 89ce02d45..82661bb30 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h @@ -112,16 +112,6 @@ #undef SDL_PLATFORM_LINUX #endif -#ifdef __NGAGE__ - -/** - * A preprocessor macro that is only defined if compiling for Nokia N-Gage. - * - * \since This macro is available since SDL 3.1.3. - */ -#define SDL_PLATFORM_NGAGE 1 -#endif - #if defined(__unix__) || defined(__unix) || defined(unix) /** @@ -367,7 +357,16 @@ #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.1.3. + */ +#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else #define SDL_WINAPI_FAMILY_PHONE 0 diff --git a/Source/ThirdParty/SDL/SDL3/SDL_process.h b/Source/ThirdParty/SDL/SDL3/SDL_process.h index 55be8d421..7cabeee04 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_process.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_process.h @@ -54,6 +54,13 @@ extern "C" { #endif +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.1.3. + * + * \sa SDL_CreateProcess + */ typedef struct SDL_Process SDL_Process; /** @@ -371,6 +378,12 @@ extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool forc * 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. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_render.h b/Source/ThirdParty/SDL/SDL3/SDL_render.h index f2dd536eb..a466a33da 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_render.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_render.h @@ -201,7 +201,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -229,7 +229,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -283,7 +283,7 @@ 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. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -320,7 +320,7 @@ 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. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -441,6 +441,11 @@ 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. @@ -474,6 +479,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. @@ -487,7 +493,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -509,7 +515,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -531,7 +537,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *re * was active, the format was unsupported, or the width or height * were out of range; call SDL_GetError() for more information. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -561,7 +567,7 @@ 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. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -671,7 +677,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * was active, the format was unsupported, or the width or height * were out of range; call SDL_GetError() for more information. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -847,7 +853,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. */ @@ -872,7 +878,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -902,7 +908,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Ui * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -923,7 +929,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *textur * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -943,7 +949,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Ui * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -969,7 +975,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *textur * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -995,7 +1001,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Ui * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1013,7 +1019,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *textur * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1031,7 +1037,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Ui * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1052,7 +1058,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *textur * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1068,7 +1074,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1088,7 +1094,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1104,7 +1110,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1135,7 +1141,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1169,7 +1175,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1201,7 +1207,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1236,7 +1242,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() * for more information. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1274,7 +1280,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1296,7 +1302,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, * * \param texture a texture locked by SDL_LockTexture(). * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1318,7 +1324,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1335,7 +1341,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1374,7 +1380,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1397,7 +1403,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer * * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1419,7 +1425,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer * * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1445,7 +1451,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Render * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1474,7 +1480,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *r * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1504,7 +1510,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *ren * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1527,7 +1533,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Rendere * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1544,7 +1550,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, c * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1564,7 +1570,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, S * \returns true if the viewport was set to a specific rectangle, or false if * it was set to NULL (the entire target). * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1589,7 +1595,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. */ @@ -1604,7 +1610,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1622,7 +1628,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, c * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1638,7 +1644,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, S * \returns true if clipping is enabled or false if not; call SDL_GetError() * for more information. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1664,7 +1670,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1681,7 +1687,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, floa * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1705,7 +1711,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, floa * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1730,7 +1736,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1754,7 +1760,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *rende * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1778,7 +1784,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1803,7 +1809,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *rende * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1819,7 +1825,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1837,7 +1843,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1853,7 +1859,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *render * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1873,7 +1879,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *render * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1890,7 +1896,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1907,7 +1913,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1926,7 +1932,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1944,7 +1950,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1 * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1961,7 +1967,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1979,7 +1985,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SD * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -1997,7 +2003,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const S * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2015,7 +2021,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, cons * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2036,7 +2042,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, con * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2065,7 +2071,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_T * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2076,6 +2082,36 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer 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 * precision. @@ -2095,7 +2131,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2129,7 +2165,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2153,7 +2189,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2185,7 +2221,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2214,7 +2250,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. */ @@ -2251,7 +2287,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2278,7 +2314,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2295,7 +2331,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2330,7 +2366,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. */ @@ -2346,7 +2382,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2369,7 +2405,7 @@ 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. * - * \threadsafety You may only call this function from the main thread. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2425,7 +2461,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *ren * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2445,7 +2481,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.3. * @@ -2496,14 +2532,43 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int * \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. + * \threadsafety This function should only be called on the main thread. * * \since This function is available since SDL 3.1.6. * + * \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/Source/ThirdParty/SDL/SDL3/SDL_revision.h b/Source/ThirdParty/SDL/SDL3/SDL_revision.h index 38a6add60..b3fa3c5de 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_revision.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_revision.h @@ -31,9 +31,9 @@ /* #undef SDL_VENDOR_INFO */ #ifdef SDL_VENDOR_INFO -#define SDL_REVISION "SDL-preview-3.1.3 (" SDL_VENDOR_INFO ")" +#define SDL_REVISION "SDL-40f9fd8 (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "SDL-preview-3.1.3" +#define SDL_REVISION "SDL-40f9fd8" #endif #endif /* SDL_revision_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_scancode.h b/Source/ThirdParty/SDL/SDL3/SDL_scancode.h index deda12fe1..1259f8008 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_scancode.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_scancode.h @@ -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_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_sensor.h b/Source/ThirdParty/SDL/SDL3/SDL_sensor.h index 138629130..008c8d687 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_sensor.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_sensor.h @@ -44,6 +44,11 @@ extern "C" { /* *INDENT-ON* */ #endif +/** + * The opaque structure used to identify an opened SDL sensor. + * + * \since This struct is available since SDL 3.1.3. + */ typedef struct SDL_Sensor SDL_Sensor; /** diff --git a/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h b/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h index 93118b5f8..4a9c525a8 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h @@ -88,14 +88,66 @@ void *alloca(size_t); # endif #endif -#ifdef SIZE_MAX +#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.1.3. + */ +#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 -#if defined(__cplusplus) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * 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.1.3. + * + * \sa SDL_assert + */ +#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) @@ -114,18 +166,10 @@ void *alloca(size_t); #endif /** - * 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. - */ -#ifdef __has_builtin -#define SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define SDL_HAS_BUILTIN(x) 0 -#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 @@ -144,6 +188,8 @@ void *alloca(size_t); * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * ``` * + * \param arg the text to turn into a string literal. + * * \since This macro is available since SDL 3.1.3. */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -434,6 +480,183 @@ typedef Sint64 SDL_Time; /* @} *//* 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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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. * (for example win32) */ @@ -530,7 +753,295 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f #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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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.1.3. + */ +#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) @@ -679,7 +1190,51 @@ extern "C" { } while (0) -#ifndef SDL_DISABLE_ALLOCA +#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.1.3. + * + * \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.1.3. + * + * \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 @@ -987,7 +1542,8 @@ 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. * @@ -1462,11 +2018,76 @@ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t si */ 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.1.3. + */ 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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) /** @@ -1705,8 +2326,72 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); /** @@ -1737,12 +2422,37 @@ 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.1.3. + */ #define SDL_copyp(dst, src) \ { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) /** - * Copy memory. + * 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. @@ -1768,7 +2478,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.1.3. + */ 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.1.3. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); /* Take advantage of compiler optimizations for memset */ @@ -1779,13 +2526,136 @@ 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.1.3. + * + * \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.1.3. + * + * \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.1.3. + * + * \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.1.3. + */ 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.1.3. + * + * \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.1.3. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); /** @@ -1804,7 +2674,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxle * \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 + * \returns the length (in wide characters, excluding the null terminator) of * `src`. * * \threadsafety It is safe to call this function from any thread. @@ -1833,7 +2703,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds * \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 + * \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. @@ -1844,8 +2714,67 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -1987,7 +2916,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar * 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. + * \returns the parsed `long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -2005,7 +2934,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, * 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`. + * \returns the length (in bytes, excluding the null terminator) of `src`. * * \threadsafety It is safe to call this function from any thread. * @@ -2028,7 +2957,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); * * \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 + * \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. @@ -2058,7 +2987,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); * \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 + * \returns the length (in characters, excluding the null terminator) of * `src`. * * \threadsafety It is safe to call this function from any thread. @@ -2088,7 +3017,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, * 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. + * \returns the number of bytes written, excluding the null terminator. * * \threadsafety It is safe to call this function from any thread. * @@ -2115,7 +3044,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char * \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 + * \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. @@ -2126,8 +3055,68 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -2172,20 +3161,372 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ +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.1.3. + * + * \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.1.3. + * + * \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.1.3. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int 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.1.3. + * + * \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.1.3. + * + * \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.1.3. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +/** + * 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.1.3. + * + * \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.1.3. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); /** @@ -2195,7 +3536,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *st * `(int)SDL_strtol(str, NULL, 10)`. * * \param str The null-terminated string to read. Must not be NULL. - * \returns The parsed `int`. + * \returns the parsed `int`. * * \threadsafety It is safe to call this function from any thread. * @@ -2218,7 +3559,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); * NULL)`. * * \param str The null-terminated string to read. Must not be NULL. - * \returns The parsed `double`. + * \returns the parsed `double`. * * \threadsafety It is safe to call this function from any thread. * @@ -2250,7 +3591,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); * 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. + * \returns the parsed `long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -2284,7 +3625,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int ba * 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. + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -2317,7 +3658,7 @@ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **en * 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. + * \returns the parsed `long long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -2350,7 +3691,7 @@ extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, * 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 + * \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. @@ -2377,11 +3718,11 @@ extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, cha * - 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. + * \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. + * \returns the parsed `double`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -2652,14 +3993,196 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const cha */ 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.1.3. + */ 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.1.3. + */ 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); + +/** + * 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.1.3. + */ 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.1.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 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.1.3. + */ 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); + +/** + * 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.1.3. + */ 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.1.3. + */ 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.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** @@ -2849,11 +4372,27 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); */ 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.1.3. + * + * \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.1.3. + * + * \sa SDL_PI_D + */ #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ #endif @@ -4038,7 +5577,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 @@ -4170,12 +5709,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.1.3. + * + * \sa SDL_iconv_open + */ typedef struct SDL_iconv_data_t *SDL_iconv_t; /** @@ -4214,7 +5754,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(). @@ -4223,21 +5778,7 @@ 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. - * - * 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. + * \returns the number of conversions on success, or a negative error code. * * \since This function is available since SDL 3.1.3. * @@ -4249,6 +5790,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. * @@ -4279,12 +5826,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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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) @@ -4398,9 +5998,9 @@ SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, si /** * 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. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_surface.h b/Source/ThirdParty/SDL/SDL3/SDL_surface.h index b69454711..5f95643cc 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_surface.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_surface.h @@ -115,6 +115,11 @@ typedef enum SDL_FlipMode * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * + * 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.1.3. * * \sa SDL_CreateSurface @@ -351,7 +356,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surfa * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns true if alternate versions are available or true otherwise. + * \returns true if alternate versions are available or false otherwise. * * \since This function is available since SDL 3.1.3. * @@ -855,7 +860,6 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac * \since This function is available since SDL 3.1.3. * * \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); @@ -871,7 +875,7 @@ 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 false on success or false on failure; call SDL_GetError() for more + * \returns true on success or false on failure; call SDL_GetError() for more * information. * * \since This function is available since SDL 3.1.3. @@ -900,7 +904,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_Pi * 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 false on success or false on failure; call SDL_GetError() for more + * \returns true on success or false on failure; call SDL_GetError() for more * information. * * \since This function is available since SDL 3.1.3. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_system.h b/Source/ThirdParty/SDL/SDL3/SDL_system.h index c144fb671..4e7181df9 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_system.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_system.h @@ -129,7 +129,29 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _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.1.3. + * + * \sa SDL_SetX11EventHook + */ typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** @@ -380,6 +402,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \since This macro is available since SDL 3.1.3. */ #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.1.3. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -468,7 +497,17 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - +/** + * 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.1.3. + * + * \sa SDL_RequestAndroidPermission + */ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test.h b/Source/ThirdParty/SDL/SDL3/SDL_test.h index e84687391..2cf83d804 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test.h - * * Include file for SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_common.h b/Source/ThirdParty/SDL/SDL3/SDL_test_common.h index aeffeb93b..8b909311f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_common.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_common.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test_common.h - * * Common functions of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h b/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h index 24bc9ee6e..db2ae6c68 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test_compare.h - * * Comparison function of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_font.h b/Source/ThirdParty/SDL/SDL3/SDL_test_font.h index 9d7b346eb..bad949e0c 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_font.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_font.h @@ -20,8 +20,6 @@ */ /* - * \file SDL_test_font.h - * * Font related functions of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h b/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h index cea0db465..925dc78ca 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test_harness.h - * * Test suite related functions of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_log.h b/Source/ThirdParty/SDL/SDL3/SDL_test_log.h index ff798d633..625d545df 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_log.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_log.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test_log.h - * * Logging related functions of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h b/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h index d751aab96..a29543988 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test_md5.h - * * MD5 related functions of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h b/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h index 16b2f6330..d1d0ef34a 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h @@ -20,8 +20,6 @@ */ /** - * \file SDL_test_memory.h - * * Memory tracking related functions of SDL test framework. * * This code is a part of the SDL test library, not the main SDL library. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_timer.h b/Source/ThirdParty/SDL/SDL3/SDL_timer.h index 62206cc77..121ba3f57 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_timer.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_timer.h @@ -38,16 +38,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.1.3. + */ #define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) /** diff --git a/Source/ThirdParty/SDL/SDL3/SDL_touch.h b/Source/ThirdParty/SDL/SDL3/SDL_touch.h index 3eb47d52d..6fbb08e69 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_touch.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_touch.h @@ -38,21 +38,49 @@ 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.1.3. + */ 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.1.3. + */ typedef Uint64 SDL_FingerID; +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.1.3. + */ 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. * @@ -68,10 +96,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.1.3. + */ #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.1.3. + */ #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) diff --git a/Source/ThirdParty/SDL/SDL3/SDL_tray.h b/Source/ThirdParty/SDL/SDL3/SDL_tray.h new file mode 100644 index 000000000..a9f482839 --- /dev/null +++ b/Source/ThirdParty/SDL/SDL3/SDL_tray.h @@ -0,0 +1,437 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2024 Sam Lantinga + + 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 + * + * System tray menu support. + */ + +#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 + +typedef struct SDL_Tray SDL_Tray; +typedef struct SDL_TrayMenu SDL_TrayMenu; +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.0.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. + * + * \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. + * Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \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. + * + * \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. May be NULL. + * + * \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. + * + * \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. + * + * \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. + * + * \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_CreateTraySubenu() 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. + * + * \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 the entries within the given menu. The pointer becomes invalid + * when any function that inserts or deletes entries in the menu is + * called. + * + * \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. + * + * \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, 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. + * + * \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. + * + * \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. + * + * \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 SDL_TRUE if the entry should be checked; SDL_FALSE + * otherwise. + * + * \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 SDL_TRUE if the entry is checked; SDL_FALSE otherwise. + * + * \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 SDL_TRUE if the entry should be enabled; SDL_FALSE + * otherwise. + * + * \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 SDL_TRUE if the entry is enabled; SDL_FALSE otherwise. + * + * \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. + * + * \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); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \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 contianing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \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. + * + * \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. + * + * \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); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_video.h b/Source/ThirdParty/SDL/SDL3/SDL_video.h index e4c9e278f..388d1e7a9 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_video.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_video.h @@ -112,7 +112,15 @@ 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.1.3. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** @@ -206,27 +214,87 @@ 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. + * + * 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.1.3. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u -#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) -#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) /** - * Used to indicate that the window position should be centered. + * 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.1.3. + */ +#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.1.3. + */ +#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) + +/** + * 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.1.3. + */ +#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.1.3. */ #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u + +/** + * Used to indicate that the window position should be centered. + * + * 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.1.3. + */ #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.1.3. + */ #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.1.3. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * @@ -249,14 +317,38 @@ typedef enum SDL_FlashOperation typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * * \since This datatype is available since SDL 3.1.3. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef int SDL_EGLint; /** @@ -419,6 +511,8 @@ typedef Uint32 SDL_GLContextResetNotification; * * \returns the number of built in video drivers. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetVideoDriver @@ -438,6 +532,8 @@ 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**. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetNumVideoDrivers @@ -454,6 +550,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetNumVideoDrivers @@ -466,6 +564,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); * * \returns the current system theme, light, dark, or unknown. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); @@ -479,6 +579,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); @@ -489,6 +591,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplays @@ -517,6 +621,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); @@ -531,6 +637,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplays @@ -547,6 +655,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa * \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.1.3. * * \sa SDL_GetDisplayUsableBounds @@ -571,6 +681,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, S * \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.1.3. * * \sa SDL_GetDisplayBounds @@ -585,6 +697,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displa * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplays @@ -598,6 +712,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplays @@ -616,6 +732,8 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * \returns the content scale of the display, or 0.0f 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.1.3. * * \sa SDL_GetDisplays @@ -642,6 +760,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplays @@ -670,6 +790,8 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * \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.1.3. * * \sa SDL_GetDisplays @@ -689,6 +811,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Display * \returns a pointer to the desktop display mode or NULL 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.1.3. * * \sa SDL_GetCurrentDisplayMode @@ -708,6 +832,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDesktopDisplayMode @@ -722,6 +848,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplayBounds @@ -737,6 +865,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetDisplayBounds @@ -752,6 +882,8 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect * * on success or 0 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.1.3. * * \sa SDL_GetDisplayBounds @@ -770,6 +902,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetWindowDisplayScale @@ -794,6 +928,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); @@ -823,6 +959,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *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.1.3. * * \sa SDL_GetWindowFullscreenMode @@ -838,6 +976,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, * \returns a pointer to the exclusive fullscreen mode to use or NULL for * borderless fullscreen desktop mode. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowFullscreenMode @@ -854,6 +994,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); @@ -866,6 +1008,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s * SDL_PIXELFORMAT_UNKNOWN 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.1.3. */ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); @@ -880,6 +1024,8 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window * allocation that 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.1.3. */ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); @@ -959,6 +1105,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreateWindowAndRenderer @@ -1019,6 +1167,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreateWindow @@ -1137,6 +1287,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreateProperties @@ -1190,6 +1342,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetWindowFromID @@ -1206,6 +1360,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetWindowID @@ -1219,6 +1375,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreatePopupWindow @@ -1341,6 +1499,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); @@ -1387,6 +1547,8 @@ 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`. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreateWindow @@ -1409,6 +1571,8 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * \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.1.3. * * \sa SDL_GetWindowTitle @@ -1422,6 +1586,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const ch * \returns the title of the window in UTF-8 format or "" if there is no * title. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowTitle @@ -1446,6 +1612,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); @@ -1453,13 +1621,12 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surfa /** * 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 @@ -1483,6 +1650,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surfa * \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.1.3. * * \sa SDL_GetWindowPosition @@ -1507,6 +1676,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x * \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.1.3. * * \sa SDL_SetWindowPosition @@ -1516,12 +1687,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int * /** * 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 @@ -1541,6 +1711,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int * * \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.1.3. * * \sa SDL_GetWindowSize @@ -1562,6 +1734,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, in * \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.1.3. * * \sa SDL_GetRenderOutputSize @@ -1586,6 +1760,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, i * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); @@ -1622,6 +1798,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_R * \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.1.3. * * \sa SDL_GetWindowAspectRatio @@ -1640,6 +1818,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, fl * \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.1.3. * * \sa SDL_SetWindowAspectRatio @@ -1675,6 +1855,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, fl * \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.1.3. * * \sa SDL_GetWindowSize @@ -1692,6 +1874,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, in * \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.1.3. * * \sa SDL_CreateWindow @@ -1708,6 +1892,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, i * \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.1.3. * * \sa SDL_GetWindowMinimumSize @@ -1726,6 +1912,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, in * \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.1.3. * * \sa SDL_GetWindowMaximumSize @@ -1742,6 +1930,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, in * \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.1.3. * * \sa SDL_GetWindowMaximumSize @@ -1760,6 +1950,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, in * \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.1.3. * * \sa SDL_GetWindowMinimumSize @@ -1781,6 +1973,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, in * \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.1.3. * * \sa SDL_GetWindowFlags @@ -1801,6 +1995,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool * \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.1.3. * * \sa SDL_GetWindowFlags @@ -1818,6 +2014,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool * \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.1.3. * * \sa SDL_GetWindowFlags @@ -1831,6 +2029,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bo * \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.1.3. * * \sa SDL_HideWindow @@ -1845,6 +2045,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *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.1.3. * * \sa SDL_ShowWindow @@ -1866,6 +2068,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); @@ -1894,6 +2098,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *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.1.3. * * \sa SDL_MinimizeWindow @@ -1905,6 +2111,9 @@ 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 been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1918,6 +2127,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *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.1.3. * * \sa SDL_MaximizeWindow @@ -1930,6 +2141,9 @@ 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 @@ -1943,6 +2157,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *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.1.3. * * \sa SDL_MaximizeWindow @@ -1972,6 +2188,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *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.1.3. * * \sa SDL_GetWindowFullscreenMode @@ -1998,6 +2216,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, boo * \returns true on success or false if the operation timed out before the * window was in the requested state. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowSize @@ -2017,6 +2237,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); * \returns true if there is a surface associated with the window, or false * otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetWindowSurface @@ -2041,6 +2263,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); * \returns the surface associated with the window, or NULL 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.1.3. * * \sa SDL_DestroyWindowSurface @@ -2068,6 +2292,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * \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.1.3. * * \sa SDL_GetWindowSurfaceVSync @@ -2086,6 +2312,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, i * \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.1.3. * * \sa SDL_SetWindowSurfaceVSync @@ -2104,6 +2332,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, i * \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.1.3. * * \sa SDL_GetWindowSurface @@ -2131,6 +2361,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *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.1.3. * * \sa SDL_GetWindowSurface @@ -2145,6 +2377,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *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.1.3. * * \sa SDL_GetWindowSurface @@ -2176,6 +2410,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *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.1.3. * * \sa SDL_GetWindowKeyboardGrab @@ -2193,6 +2429,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, b * \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.1.3. * * \sa SDL_GetWindowMouseRect @@ -2208,6 +2446,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool * \param window the window to query. * \returns true if keyboard is grabbed, and false otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowKeyboardGrab @@ -2220,6 +2460,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); * \param window the window to query. * \returns true if mouse is grabbed, and false otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GetWindowMouseRect @@ -2234,6 +2476,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); * * \returns the window if input is grabbed or NULL otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowMouseGrab @@ -2253,6 +2497,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \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.1.3. * * \sa SDL_GetWindowMouseRect @@ -2268,6 +2514,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, cons * \returns a pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SetWindowMouseRect @@ -2289,6 +2537,8 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_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.1.3. * * \sa SDL_GetWindowOpacity @@ -2305,6 +2555,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f 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.1.3. * * \sa SDL_SetWindowOpacity @@ -2337,6 +2589,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *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.1.3. * * \sa SDL_SetWindowModal @@ -2354,6 +2608,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Win * \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.1.3. * * \sa SDL_SetWindowParent @@ -2369,6 +2625,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool mod * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); @@ -2393,6 +2651,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); @@ -2400,6 +2660,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, in /** * Possible return values from the SDL_HitTest callback. * + * \threadsafety This function should only be called on the main thread. + * * \since This enum is available since SDL 3.1.3. * * \sa SDL_HitTest @@ -2470,6 +2732,8 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); @@ -2496,6 +2760,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_Hi * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); @@ -2508,6 +2774,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surf * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); @@ -2520,6 +2788,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOp * * \param window the window to destroy. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CreatePopupWindow @@ -2538,6 +2808,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * \returns true if the screensaver is enabled, false if it is disabled. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_DisableScreenSaver @@ -2551,6 +2823,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); * \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.1.3. * * \sa SDL_DisableScreenSaver @@ -2570,6 +2844,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); * \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.1.3. * * \sa SDL_EnableScreenSaver @@ -2598,6 +2874,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); * \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.1.3. * * \sa SDL_GL_GetProcAddress @@ -2650,6 +2928,8 @@ extern SDL_DECLSPEC 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GL_ExtensionSupported @@ -2669,6 +2949,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_EGL_GetCurrentDisplay @@ -2678,6 +2960,8 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha /** * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GL_LoadLibrary @@ -2701,6 +2985,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * \param extension the name of the extension to check. * \returns true if the extension is supported, false otherwise. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); @@ -2708,6 +2994,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension /** * Reset all previously set OpenGL context attributes to their default values. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GL_GetAttribute @@ -2729,6 +3017,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * \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.1.3. * * \sa SDL_GL_GetAttribute @@ -2745,6 +3035,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value) * \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.1.3. * * \sa SDL_GL_ResetAttributes @@ -2767,6 +3059,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value * \returns the OpenGL context associated with `window` or NULL 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.1.3. * * \sa SDL_GL_DestroyContext @@ -2784,6 +3078,8 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * \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.1.3. * * \sa SDL_GL_CreateContext @@ -2796,6 +3092,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLCo * \returns the currently active OpenGL window on success or NULL 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.1.3. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); @@ -2806,6 +3104,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_GL_MakeCurrent @@ -2818,6 +3118,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); @@ -2828,6 +3130,8 @@ 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. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); @@ -2839,6 +3143,8 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); * \returns the EGLSurface pointer associated with the window, or NULL on * failure. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); @@ -2859,6 +3165,8 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * eglCreateContext. May be NULL. * \param userdata a pointer that is passed to the callbacks. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, @@ -2888,6 +3196,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * \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.1.3. * * \sa SDL_GL_GetSwapInterval @@ -2907,6 +3217,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); * \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.1.3. * * \sa SDL_GL_SetSwapInterval @@ -2927,6 +3239,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); * \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.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); @@ -2938,6 +3252,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *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.1.3. * * \sa SDL_GL_CreateContext diff --git a/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs b/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs index ecaa5186f..c2619eae1 100644 --- a/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs +++ b/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs @@ -88,8 +88,8 @@ namespace Flax.Deps.Dependencies Path.Combine(root, "include", "SDL3"), }; - CloneGitRepoFastSince(root, "https://github.com/libsdl-org/SDL.git", new DateTime(2024, 12, 1)); - GitResetToCommit(root, "acf0f09320ec75528d74b1fd160090ea262c0698"); + CloneGitRepoFastSince(root, "https://github.com/libsdl-org/SDL.git", new DateTime(2024, 12, 24)); + GitResetToCommit(root, "0becdad3920bd5d678ddff832bd3698356a39dee"); foreach (var platform in options.Platforms) {