From c37713764087e579017cafe63510b0b352ff4f36 Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Mon, 20 Jan 2025 22:30:30 +0200 Subject: [PATCH] Update SDL3 --- Source/ThirdParty/SDL/SDL3/SDL.h | 2 +- Source/ThirdParty/SDL/SDL3/SDL_assert.h | 8 +- Source/ThirdParty/SDL/SDL3/SDL_asyncio.h | 6 +- Source/ThirdParty/SDL/SDL3/SDL_audio.h | 22 +++- Source/ThirdParty/SDL/SDL3/SDL_events.h | 23 ++-- Source/ThirdParty/SDL/SDL3/SDL_filesystem.h | 6 + Source/ThirdParty/SDL/SDL3/SDL_gpu.h | 113 ++++++++++++++---- Source/ThirdParty/SDL/SDL3/SDL_hints.h | 79 +++++++++++- Source/ThirdParty/SDL/SDL3/SDL_iostream.h | 97 ++++++++++++++- Source/ThirdParty/SDL/SDL3/SDL_messagebox.h | 13 +- Source/ThirdParty/SDL/SDL3/SDL_mouse.h | 36 +++++- Source/ThirdParty/SDL/SDL3/SDL_mutex.h | 16 ++- Source/ThirdParty/SDL/SDL3/SDL_pen.h | 16 +++ Source/ThirdParty/SDL/SDL3/SDL_power.h | 9 ++ Source/ThirdParty/SDL/SDL3/SDL_render.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_revision.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_sensor.h | 2 + Source/ThirdParty/SDL/SDL3/SDL_storage.h | 30 ++++- Source/ThirdParty/SDL/SDL3/SDL_test_common.h | 1 + Source/ThirdParty/SDL/SDL3/SDL_thread.h | 14 ++- Source/ThirdParty/SDL/SDL3/SDL_time.h | 8 ++ Source/ThirdParty/SDL/SDL3/SDL_timer.h | 24 +++- Source/ThirdParty/SDL/SDL3/SDL_touch.h | 13 +- Source/ThirdParty/SDL/SDL3/SDL_tray.h | 99 +++++++++++++-- Source/ThirdParty/SDL/SDL3/SDL_version.h | 2 +- Source/ThirdParty/SDL/SDL3/SDL_video.h | 3 +- .../Tools/Flax.Build/Deps/Dependencies/SDL.cs | 6 +- 27 files changed, 578 insertions(+), 78 deletions(-) diff --git a/Source/ThirdParty/SDL/SDL3/SDL.h b/Source/ThirdParty/SDL/SDL3/SDL.h index 3dba4228b..65a852176 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL.h +++ b/Source/ThirdParty/SDL/SDL3/SDL.h @@ -20,7 +20,7 @@ */ /** - * Main include header for the SDL library, version 3.1.9 + * Main include header for the SDL library, version 3.1.11 * * It is almost always best to include just this one header instead of * picking out individual headers included here. There are exceptions to diff --git a/Source/ThirdParty/SDL/SDL3/SDL_assert.h b/Source/ThirdParty/SDL/SDL3/SDL_assert.h index e6860ce32..edc69cd7e 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_assert.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_assert.h @@ -118,8 +118,7 @@ extern "C" { * * If the program is not running under a debugger, SDL_TriggerBreakpoint will * likely terminate the app, possibly without warning. If the current platform - * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro - * does nothing. + * isn't supported, this macro is left undefined. * * \threadsafety It is safe to call this macro from any thread. * @@ -138,6 +137,8 @@ extern "C" { #define SDL_TriggerBreakpoint() assert(0) #elif SDL_HAS_BUILTIN(__builtin_debugtrap) #define SDL_TriggerBreakpoint() __builtin_debugtrap() +#elif SDL_HAS_BUILTIN(__builtin_trap) + #define SDL_TriggerBreakpoint() __builtin_trap() #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) @@ -154,8 +155,7 @@ extern "C" { #include #define SDL_TriggerBreakpoint() raise(SIGTRAP) #else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ #endif #ifdef SDL_WIKI_DOCUMENTATION_SECTION diff --git a/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h b/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h index ee13bf3ae..33124e93f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_asyncio.h @@ -67,14 +67,14 @@ * * ## Best Practices * - * Simple non-blocking i/o--for an app that just wants to pick up data + * 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 + * 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 @@ -83,7 +83,7 @@ * 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 + * 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 diff --git a/Source/ThirdParty/SDL/SDL3/SDL_audio.h b/Source/ThirdParty/SDL/SDL3/SDL_audio.h index fdfc376ae..71457abbe 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_audio.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_audio.h @@ -942,7 +942,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * Binding a stream to a device will set its output format for playback * devices, and its input format for recording devices, so they match the * device's settings. The caller is welcome to change the other end of the - * stream's format at any time. + * stream's format at any time with SDL_SetAudioStreamFormat(). * * \param devid an audio device to bind a stream to. * \param streams an array of audio streams to bind. @@ -1104,6 +1104,12 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *strea * next sound file, and start putting that new data while the previous sound * file is still queued, and everything will still play back correctly. * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * * \param stream the stream the format is being changed. * \param src_spec the new format of the audio input; if NULL, it is not * changed. @@ -1298,6 +1304,11 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. @@ -1349,6 +1360,13 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStre * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. @@ -1589,7 +1607,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *st * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.2.0. + * \since This function is available since SDL 3.1.10. * * \sa SDL_PauseAudioStreamDevice * \sa SDL_ResumeAudioStreamDevice diff --git a/Source/ThirdParty/SDL/SDL3/SDL_events.h b/Source/ThirdParty/SDL/SDL3/SDL_events.h index 1cde3811e..df62ca62f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_events.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_events.h @@ -38,10 +38,10 @@ * 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. + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. * * The app is free to generate their own events, too: SDL_PushEvent allows the * app to put events onto the queue for later retrieval; SDL_RegisterEvents @@ -1377,8 +1377,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. + * + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. * * If the filter function returns true when called, then the event will be * added to the internal queue. If it returns false, then the event will be @@ -1392,17 +1395,9 @@ typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h b/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h index c228a0382..813668426 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h @@ -313,6 +313,9 @@ typedef enum SDL_EnumerationResult * terminate the enumeration early, and dictate the return value of the * enumeration function itself. * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * * \param userdata an app-controlled pointer that is passed to the callback. * \param dirname the directory that is being enumerated. * \param fname the next entry in the enumeration. @@ -480,6 +483,9 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const ch * platforms without this concept, this would cause surprises with file access * outside of SDL. * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * * \returns a UTF-8 string of the current working directory in * platform-dependent notation. NULL if there's a problem. This * should be freed with SDL_free() when it is no longer needed. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_gpu.h b/Source/ThirdParty/SDL/SDL3/SDL_gpu.h index d4b92b9d7..59315a1be 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_gpu.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_gpu.h @@ -334,7 +334,6 @@ typedef struct SDL_GPUDevice SDL_GPUDevice; * \since This struct is available since SDL 3.1.3 * * \sa SDL_CreateGPUBuffer - * \sa SDL_SetGPUBufferName * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer * \sa SDL_CopyGPUBufferToBuffer @@ -374,7 +373,6 @@ typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; * \since This struct is available since SDL 3.1.3 * * \sa SDL_CreateGPUTexture - * \sa SDL_SetGPUTextureName * \sa SDL_UploadToGPUTexture * \sa SDL_DownloadFromGPUTexture * \sa SDL_CopyGPUTextureToTexture @@ -517,6 +515,20 @@ typedef struct SDL_GPUFence SDL_GPUFence; /** * Specifies the primitive topology of a graphics pipeline. * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * * \since This enum is available since SDL 3.1.3 * * \sa SDL_CreateGPUGraphicsPipeline @@ -2247,6 +2259,12 @@ extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUD * - [[texture]]: Sampled textures, followed by read-only storage textures, * followed by read-write storage textures * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the compute pipeline to * create. @@ -2262,9 +2280,17 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline SDL_GPUDevice *device, const SDL_GPUComputePipelineCreateInfo *createinfo); +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" + /** * Creates a pipeline object to be used in a graphics workflow. * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the graphics pipeline to * create. @@ -2281,10 +2307,18 @@ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeli SDL_GPUDevice *device, const SDL_GPUGraphicsPipelineCreateInfo *createinfo); +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" + /** * Creates a sampler object to be used when binding textures in a graphics * workflow. * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the sampler to create. * \returns a sampler object on success, or NULL on failure; call @@ -2300,6 +2334,8 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( SDL_GPUDevice *device, const SDL_GPUSamplerCreateInfo *createinfo); +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" + /** * Creates a shader to be used when creating a graphics pipeline. * @@ -2357,6 +2393,12 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with * SDL_CreateGPUDeviceWithProperties(). * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the shader to create. * \returns a shader object on success, or NULL on failure; call @@ -2371,6 +2413,8 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( SDL_GPUDevice *device, const SDL_GPUShaderCreateInfo *createinfo); +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" + /** * Creates a texture object to be used in graphics or compute workflows. * @@ -2387,27 +2431,26 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * 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 + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture * to a color with this red intensity. Defaults to zero. - * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture * to a color with this green intensity. Defaults to zero. - * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture * to a color with this blue intensity. Defaults to zero. - * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture * to a color with this alpha intensity. Defaults to zero. - * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear * the texture to a depth of this value. Defaults to zero. - * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. * * \param device a GPU Context. * \param createinfo a struct describing the state of the texture to create. @@ -2431,13 +2474,13 @@ 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" - +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" /** * Creates a buffer object to be used in graphics or compute workflows. @@ -2453,6 +2496,12 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) * . * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the buffer to create. * \returns a buffer object on success, or NULL on failure; call @@ -2460,7 +2509,6 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * * \since This function is available since SDL 3.1.3. * - * \sa SDL_SetGPUBufferName * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer * \sa SDL_CopyGPUBufferToBuffer @@ -2478,6 +2526,8 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( SDL_GPUDevice *device, const SDL_GPUBufferCreateInfo *createinfo); +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" + /** * Creates a transfer buffer to be used when uploading to or downloading from * graphics resources. @@ -2485,6 +2535,12 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( * Download buffers can be particularly expensive to create, so it is good * practice to reuse them if data will be downloaded regularly. * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the transfer buffer to * create. @@ -2503,18 +2559,26 @@ extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( SDL_GPUDevice *device, const SDL_GPUTransferBufferCreateInfo *createinfo); +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" + /* Debug Naming */ /** * Sets an arbitrary string constant to label a buffer. * - * Useful for debugging. + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. * * \param device a GPU Context. * \param buffer a buffer to attach the name to. * \param text a UTF-8 string constant to mark as the name of the buffer. * + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * * \since This function is available since SDL 3.1.3. + * + * \sa SDL_CreateGPUBuffer */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( SDL_GPUDevice *device, @@ -2524,13 +2588,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( /** * Sets an arbitrary string constant to label a texture. * - * Useful for debugging. + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. * * \param device a GPU Context. * \param texture a texture to attach the name to. * \param text a UTF-8 string constant to mark as the name of the texture. * + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * * \since This function is available since SDL 3.1.3. + * + * \sa SDL_CreateGPUTexture */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( SDL_GPUDevice *device, diff --git a/Source/ThirdParty/SDL/SDL3/SDL_hints.h b/Source/ThirdParty/SDL/SDL3/SDL_hints.h index 263e0a1a2..9f6b58ba4 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_hints.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_hints.h @@ -730,6 +730,7 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all * - any other string without a leading # sign applies to the element on the * page with that ID. * @@ -2347,6 +2348,31 @@ extern "C" { */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" +/** + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since 3.2.0 + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + /** * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have * momentum on macOS. @@ -2534,7 +2560,7 @@ extern "C" { * - "1": Relative mouse motion will be scaled using the system mouse * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after * system speed scale. * * This hint can be set anytime. @@ -3330,6 +3356,27 @@ extern "C" { */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.1.9. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + /** * A variable controlling whether fullscreen windows are minimized when they * lose focus. @@ -4164,6 +4211,36 @@ extern "C" { */ #define SDL_HINT_ASSERT "SDL_ASSERT" +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + /** * An enumeration of hint priorities. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_iostream.h b/Source/ThirdParty/SDL/SDL3/SDL_iostream.h index ca2bf275b..a45a12d01 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_iostream.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_iostream.h @@ -260,6 +260,8 @@ typedef struct SDL_IOStream SDL_IOStream; * \returns a pointer to the SDL_IOStream structure that is created or NULL on * failure; call SDL_GetError() for more information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CloseIO @@ -303,6 +305,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_IOFromConstMem @@ -347,6 +351,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_IOFromMem @@ -375,6 +381,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CloseIO @@ -408,6 +416,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * \returns a pointer to the allocated memory on success or NULL on failure; * call SDL_GetError() for more information. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_CloseIO @@ -442,6 +452,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * \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_OpenIO @@ -455,6 +467,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); * \returns a valid property ID on success or 0 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. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); @@ -473,8 +487,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *c * \param context the SDL_IOStream to query. * \returns an SDL_IOStatus enum with the current state. * - * \threadsafety This function should not be called at the same time that - * another thread is operating on the same SDL_IOStream. + * \threadsafety This function is not thread safe. * * \since This function is available since SDL 3.1.3. */ @@ -488,6 +501,8 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); * negative error code 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. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); @@ -513,6 +528,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * \returns the final offset in the data stream after the seek or -1 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_TellIO @@ -531,6 +548,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs * \returns the current offset in the stream, or -1 if the information can not * be determined. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_SeekIO @@ -554,6 +573,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * \returns the number of bytes read, or 0 on end of file or other failure; * call SDL_GetError() for more information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_WriteIO @@ -581,6 +602,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \returns the number of bytes written, which will be less than `size` on * failure; call SDL_GetError() for more information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_IOprintf @@ -603,6 +626,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_IOvprintf @@ -621,6 +646,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_IOprintf @@ -639,6 +666,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * \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_OpenIO @@ -663,6 +692,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); * \returns the data or NULL on failure; call SDL_GetError() for more * information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_LoadFile @@ -684,6 +715,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da * \returns the data or NULL on failure; call SDL_GetError() for more * information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. * * \sa SDL_LoadFile_IO @@ -703,6 +736,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi * \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.8. * * \sa SDL_SaveFile @@ -720,6 +755,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void * * \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.8. * * \sa SDL_SaveFile_IO @@ -747,6 +784,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data * \returns true on success or false on failure or EOF; call SDL_GetError() * for more information. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.1.3. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); @@ -764,6 +803,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); * \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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); @@ -785,6 +826,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); @@ -806,6 +849,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); @@ -827,6 +872,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); @@ -848,6 +895,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); @@ -869,6 +918,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); @@ -890,6 +941,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); @@ -911,6 +964,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); @@ -932,6 +987,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); @@ -953,6 +1010,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); @@ -974,6 +1033,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); @@ -995,6 +1056,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); @@ -1016,6 +1079,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); @@ -1036,6 +1101,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); @@ -1048,6 +1115,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); @@ -1065,6 +1134,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); @@ -1082,6 +1153,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); @@ -1098,6 +1171,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); @@ -1114,6 +1189,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); @@ -1131,6 +1208,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); @@ -1148,6 +1227,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); @@ -1164,6 +1245,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); @@ -1180,6 +1263,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); @@ -1197,6 +1282,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); @@ -1214,6 +1301,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); @@ -1230,6 +1319,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); @@ -1246,6 +1337,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value) * \returns true on successful write 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. */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); diff --git a/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h b/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h index b4bb08273..862205ccc 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h @@ -22,7 +22,18 @@ /** * # CategoryMessagebox * - * Message box support routines. + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. */ #ifndef SDL_messagebox_h_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_mouse.h b/Source/ThirdParty/SDL/SDL3/SDL_mouse.h index e6d09bfc0..d0ec3e6cc 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_mouse.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_mouse.h @@ -22,7 +22,36 @@ /** * # CategoryMouse * - * SDL mouse handling. + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. */ #ifndef SDL_mouse_h_ @@ -359,6 +388,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * report continuous relative mouse motion even if the mouse is at the edge of * the window. * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * * This function will flush any pending mouse motion for this window. * * \param window the window to change. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_mutex.h b/Source/ThirdParty/SDL/SDL3/SDL_mutex.h index de66c945a..b60d8421a 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_mutex.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_mutex.h @@ -25,7 +25,19 @@ /** * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. */ #include @@ -963,7 +975,7 @@ typedef enum SDL_InitStatus * { * if (!SDL_ShouldQuit(&init)) { * // The system is not initialized - * return true; + * return; * } * * // At this point, you should not leave this function without calling SDL_SetInitialized() diff --git a/Source/ThirdParty/SDL/SDL3/SDL_pen.h b/Source/ThirdParty/SDL/SDL3/SDL_pen.h index 838be6d4f..61305905a 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_pen.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_pen.h @@ -40,6 +40,8 @@ #define SDL_pen_h_ #include +#include +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -59,6 +61,20 @@ extern "C" { */ typedef Uint32 SDL_PenID; +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + /** * Pen input flags, as reported by various pen events' `pen_state` field. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_power.h b/Source/ThirdParty/SDL/SDL3/SDL_power.h index 720b1066b..1df471b9f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_power.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_power.h @@ -26,6 +26,15 @@ * # CategoryPower * * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ #include diff --git a/Source/ThirdParty/SDL/SDL3/SDL_render.h b/Source/ThirdParty/SDL/SDL3/SDL_render.h index d7428b075..56a6770f9 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_render.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_render.h @@ -1273,8 +1273,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. * \returns true on success or false on failure; call SDL_GetError() for more * information. * diff --git a/Source/ThirdParty/SDL/SDL3/SDL_revision.h b/Source/ThirdParty/SDL/SDL3/SDL_revision.h index abc6ed0dd..493c7b320 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 "SDL3-3.1.9-preview-3.1.8-43-g82125ec1d (" SDL_VENDOR_INFO ")" +#define SDL_REVISION "SDL3-3.1.11-prerelease-3.1.10-73-g819628c6b (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "SDL3-3.1.9-preview-3.1.8-43-g82125ec1d" +#define SDL_REVISION "SDL3-3.1.11-prerelease-3.1.10-73-g819628c6b" #endif #endif /* SDL_revision_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_sensor.h b/Source/ThirdParty/SDL/SDL3/SDL_sensor.h index 1377c1021..83e70839b 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_sensor.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_sensor.h @@ -24,6 +24,8 @@ * * SDL sensor management. * + * These APIs grant access to gyros and accelerometers on various platforms. + * * In order to use these functions, SDL_Init() must have been called with the * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and * load appropriate drivers. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_storage.h b/Source/ThirdParty/SDL/SDL3/SDL_storage.h index e5ef689f1..25e19f317 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_storage.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_storage.h @@ -112,8 +112,8 @@ * validated, so an error occurring elsewhere in the program may result in * missing/corrupted save data * - * When using, SDL_Storage, these types of problems are virtually impossible - * to trip over: + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: * * ```c * void ReadGameData(void) @@ -222,6 +222,22 @@ * playing on another PC (and vice versa) with the save data fully * synchronized across all devices, allowing for a seamless experience without * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. */ #ifndef SDL_storage_h_ @@ -527,8 +543,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries * were enumerated. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. * \returns true on success or false on failure; call SDL_GetError() for more @@ -630,8 +649,11 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param pattern the pattern that files in the directory must match. Can be * NULL. * \param flags `SDL_GLOB_*` bitflags that affect this search. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_common.h b/Source/ThirdParty/SDL/SDL3/SDL_test_common.h index 2d39bcf52..3ab1ad01c 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_common.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_common.h @@ -139,6 +139,7 @@ typedef struct int gl_accum_blue_size; int gl_accum_alpha_size; int gl_stereo; + int gl_release_behavior; int gl_multisamplebuffers; int gl_multisamplesamples; int gl_retained_backing; diff --git a/Source/ThirdParty/SDL/SDL3/SDL_thread.h b/Source/ThirdParty/SDL/SDL3/SDL_thread.h index d7d83edb5..240812db1 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_thread.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_thread.h @@ -25,7 +25,19 @@ /** * # CategoryThread * - * SDL thread management routines. + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. */ #include diff --git a/Source/ThirdParty/SDL/SDL3/SDL_time.h b/Source/ThirdParty/SDL/SDL3/SDL_time.h index c1880dce7..cc611984d 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_time.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_time.h @@ -26,6 +26,14 @@ freely, subject to the following restrictions: * # CategoryTime * * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. */ #include diff --git a/Source/ThirdParty/SDL/SDL3/SDL_timer.h b/Source/ThirdParty/SDL/SDL3/SDL_timer.h index c0b6bd3f5..24815880d 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_timer.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_timer.h @@ -25,7 +25,20 @@ /** * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. */ #include @@ -239,6 +252,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.1.3. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); @@ -254,6 +270,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.1.3. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); @@ -269,6 +288,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.1.6. + * + * \sa SDL_Delay + * \sa SDL_DelayNS */ extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); diff --git a/Source/ThirdParty/SDL/SDL3/SDL_touch.h b/Source/ThirdParty/SDL/SDL3/SDL_touch.h index 0f32e11eb..1260f573d 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_touch.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_touch.h @@ -22,7 +22,18 @@ /** * # CategoryTouch * - * SDL touch management. + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. */ #ifndef SDL_touch_h_ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_tray.h b/Source/ThirdParty/SDL/SDL3/SDL_tray.h index 9830b966c..83bd3b787 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_tray.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_tray.h @@ -22,7 +22,11 @@ /** * # CategoryTray * - * System tray menu support. + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. */ #ifndef SDL_tray_h_ @@ -106,6 +110,8 @@ typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); * UTF-8 encoding. Not supported on all platforms. May be NULL. * \returns The newly created system tray icon. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTrayMenu @@ -120,6 +126,9 @@ extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const ch * \param tray the tray icon to be updated. * \param icon the new icon. May be NULL. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray @@ -132,6 +141,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *ic * \param tray the tray icon to be updated. * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray @@ -151,6 +163,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char * * \param tray the tray to bind the menu to. * \returns the newly created menu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray @@ -172,6 +187,9 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); * \param entry the tray entry to bind the menu to. * \returns the newly created menu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_InsertTrayEntryAt @@ -194,6 +212,9 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *e * \param tray the tray entry to bind the menu to. * \returns the newly created menu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray @@ -204,7 +225,7 @@ 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 + * You should have called SDL_CreateTraySubmenu() on the entry object. This * function allows you to fetch it again later. * * This function does the same thing as SDL_GetTrayMenu(), except that it @@ -215,6 +236,9 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); * \param entry the tray entry to bind the menu to. * \returns the newly created menu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_InsertTrayEntryAt @@ -232,6 +256,9 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entr * pointer becomes invalid when any function that inserts or deletes * entries in the menu is called. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_RemoveTrayEntry @@ -244,6 +271,9 @@ extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMen * * \param entry The entry to be deleted. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries @@ -267,6 +297,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); * \param flags a combination of flags, some of which are mandatory. * \returns the newly created entry, or NULL if pos is out of bounds. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_TrayEntryFlags @@ -287,6 +320,9 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *m * \param entry the entry to be updated. * \param label the new label for the entry in UTF-8 encoding. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries @@ -303,6 +339,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, con * \param entry the entry to be read. * \returns the label of the entry in UTF-8 encoding. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries @@ -317,8 +356,10 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *ent * 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. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. * * \since This function is available since SDL 3.1.8. * @@ -334,7 +375,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, b * 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. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. * * \since This function is available since SDL 3.1.8. * @@ -348,8 +392,10 @@ 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. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. * * \since This function is available since SDL 3.1.8. * @@ -363,7 +409,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, b * 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. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. * * \since This function is available since SDL 3.1.8. * @@ -381,6 +430,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries @@ -393,7 +445,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, * * \param entry The entry to activate. * - * \since This function is available since SDL 3.2.0. + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.1.10. */ extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); @@ -404,6 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); * * \param tray the tray icon to be destroyed. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray @@ -411,11 +469,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); /** - * Gets the menu contianing a certain tray entry. + * Gets the menu containing a certain tray entry. * * \param entry the entry for which to get the parent menu. * \returns the parent menu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_InsertTrayEntryAt @@ -432,6 +493,9 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry * * \param menu the menu for which to get the parent entry. * \returns the parent entry, or NULL if this menu is not a submenu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTraySubmenu @@ -449,6 +513,9 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMe * \param menu the menu for which to get the parent enttrayry. * \returns the parent tray, or NULL if this menu is a submenu. * + * \threadsafety This function should be called on the thread that created the + * tray. + * * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTrayMenu @@ -456,6 +523,18 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMe */ extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/Source/ThirdParty/SDL/SDL3/SDL_version.h b/Source/ThirdParty/SDL/SDL3/SDL_version.h index 692d49399..57f7aca9c 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_version.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_version.h @@ -62,7 +62,7 @@ extern "C" { * * \since This macro is available since SDL 3.1.3. */ -#define SDL_MICRO_VERSION 9 +#define SDL_MICRO_VERSION 11 /** * This macro turns the version numbers into a numeric value. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_video.h b/Source/ThirdParty/SDL/SDL3/SDL_video.h index 00b98b330..43e471799 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_video.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_video.h @@ -648,7 +648,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa /** * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. diff --git a/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs b/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs index 08855e92a..08101c631 100644 --- a/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs +++ b/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs @@ -48,7 +48,7 @@ namespace Flax.Deps.Dependencies public override void Build(BuildOptions options) { string root = options.IntermediateFolder; - string configuration = "Debug"; + string configuration = "Release"; const bool buildStatic = true; var configs = new string[] { @@ -88,8 +88,8 @@ namespace Flax.Deps.Dependencies Path.Combine(root, "include", "SDL3"), }; - CloneGitRepoFastSince(root, "https://github.com/libsdl-org/SDL", new DateTime(2025, 01, 10)); - GitResetToCommit(root, "82125ec1d888e95f838b3cd683dfc8aa54013371"); + CloneGitRepoFastSince(root, "https://github.com/libsdl-org/SDL", new DateTime(2025, 01, 19)); + GitResetToCommit(root, "819628c6bf8e6c3e5357d7ee4bd2d3d43ddfe052"); foreach (var platform in options.Platforms) {