Update vendor:sdl3 to version 3.2.10

vendor/sdl3/include/SDL_gpu.h

@@ -35,13 +35,14 @@
  * can render offscreen entirely, perhaps for image processing, and not use a
  * window at all.
  *
- * Next the app prepares static data (things that are created once and used
+ * Next, the app prepares static data (things that are created once and used
  * over and over). For example:
  *
  * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader().
- * - Vertex buffers (arrays of geometry data) and other data rendering will
- *   need: use SDL_UploadToGPUBuffer().
- * - Textures (images): use SDL_UploadToGPUTexture().
+ * - Vertex buffers (arrays of geometry data) and other rendering data: use
+ *   SDL_CreateGPUBuffer() and SDL_UploadToGPUBuffer().
+ * - Textures (images): use SDL_CreateGPUTexture() and
+ *   SDL_UploadToGPUTexture().
  * - Samplers (how textures should be read from): use SDL_CreateGPUSampler().
  * - Render pipelines (precalculated rendering state): use
  *   SDL_CreateGPUGraphicsPipeline()
@@ -130,7 +131,8 @@
  * It is optimal for apps to pre-compile the shader formats they might use,
  * but for ease of use SDL provides a separate project,
  * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross)
- * , for performing runtime shader cross-compilation.
+ * , for performing runtime shader cross-compilation. It also has a CLI
+ * interface for offline precompilation as well.
  *
  * This is an extremely quick overview that leaves out several important
  * details. Already, though, one can see that GPU programming can be quite
@@ -888,6 +890,10 @@ typedef enum SDL_GPUCubeMapFace
  * Unlike textures, READ | WRITE can be used for simultaneous read-write
  * usage. The same data synchronization concerns as textures apply.
  *
+ * If you use a STORAGE flag, the data in the buffer must respect std140
+ * layout conventions. In practical terms this means you must ensure that vec3
+ * and vec4 fields are 16-byte aligned.
+ *
  * \since This datatype is available since SDL 3.2.0.
  *
  * \sa SDL_CreateGPUBuffer
@@ -1361,6 +1367,7 @@ typedef struct SDL_GPUTextureLocation
  *
  * \sa SDL_UploadToGPUTexture
  * \sa SDL_DownloadFromGPUTexture
+ * \sa SDL_CreateGPUTexture
  */
 typedef struct SDL_GPUTextureRegion
 {
@@ -1489,9 +1496,16 @@ typedef struct SDL_GPUIndirectDispatchCommand
 /**
  * A structure specifying the parameters of a sampler.
  *
+ * Note that mip_lod_bias is a no-op for the Metal driver. For Metal, LOD bias
+ * must be applied via shader instead.
+ *
  * \since This function is available since SDL 3.2.0.
  *
  * \sa SDL_CreateGPUSampler
+ * \sa SDL_GPUFilter
+ * \sa SDL_GPUSamplerMipmapMode
+ * \sa SDL_GPUSamplerAddressMode
+ * \sa SDL_GPUCompareOp
  */
 typedef struct SDL_GPUSamplerCreateInfo
 {
@@ -1530,14 +1544,14 @@ typedef struct SDL_GPUSamplerCreateInfo
  * \since This struct is available since SDL 3.2.0.
  *
  * \sa SDL_GPUVertexAttribute
- * \sa SDL_GPUVertexInputState
+ * \sa SDL_GPUVertexInputRate
  */
 typedef struct SDL_GPUVertexBufferDescription
 {
     Uint32 slot;                        /**< The binding slot of the vertex buffer. */
     Uint32 pitch;                       /**< The byte pitch between consecutive elements of the vertex buffer. */
     SDL_GPUVertexInputRate input_rate;  /**< Whether attribute addressing is a function of the vertex index or instance index. */
-    Uint32 instance_step_rate;          /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */
+    Uint32 instance_step_rate;          /**< Reserved for future use. Must be set to 0. */
 } SDL_GPUVertexBufferDescription;
 
 /**
@@ -1550,6 +1564,7 @@ typedef struct SDL_GPUVertexBufferDescription
  *
  * \sa SDL_GPUVertexBufferDescription
  * \sa SDL_GPUVertexInputState
+ * \sa SDL_GPUVertexElementFormat
  */
 typedef struct SDL_GPUVertexAttribute
 {
@@ -1706,10 +1721,13 @@ typedef struct SDL_GPUTransferBufferCreateInfo
  * A structure specifying the parameters of the graphics pipeline rasterizer
  * state.
  *
- * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if
- * enable_depth_clip is true. If you rely on this clamp+clip behavior,
- * consider enabling depth clip and then manually clamping depth in your
- * fragment shaders on Metal and Vulkan.
+ * Note that SDL_GPU_FILLMODE_LINE is not supported on many Android devices.
+ * For those devices, the fill mode will automatically fall back to FILL.
+ *
+ * Also note that the D3D12 driver will enable depth clamping even if
+ * enable_depth_clip is true. If you need this clamp+clip behavior, consider
+ * enabling depth clip and then manually clamping depth in your fragment
+ * shaders on Metal and Vulkan.
  *
  * \since This struct is available since SDL 3.2.0.
  *
@@ -1740,8 +1758,8 @@ typedef struct SDL_GPURasterizerState
 typedef struct SDL_GPUMultisampleState
 {
     SDL_GPUSampleCount sample_count;  /**< The number of samples to be used in rasterization. */
-    Uint32 sample_mask;               /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */
-    bool enable_mask;             /**< Enables sample masking. */
+    Uint32 sample_mask;               /**< Reserved for future use. Must be set to 0. */
+    bool enable_mask;             /**< Reserved for future use. Must be set to false. */
     Uint8 padding1;
     Uint8 padding2;
     Uint8 padding3;
@@ -1791,6 +1809,8 @@ typedef struct SDL_GPUColorTargetDescription
  * \since This struct is available since SDL 3.2.0.
  *
  * \sa SDL_GPUGraphicsPipelineCreateInfo
+ * \sa SDL_GPUColorTargetDescription
+ * \sa SDL_GPUTextureFormat
  */
 typedef struct SDL_GPUGraphicsPipelineTargetInfo
 {
@@ -1809,6 +1829,7 @@ typedef struct SDL_GPUGraphicsPipelineTargetInfo
  * \since This struct is available since SDL 3.2.0.
  *
  * \sa SDL_CreateGPUGraphicsPipeline
+ * \sa SDL_GPUShader
  * \sa SDL_GPUVertexInputState
  * \sa SDL_GPUPrimitiveType
  * \sa SDL_GPURasterizerState
@@ -1836,6 +1857,7 @@ typedef struct SDL_GPUGraphicsPipelineCreateInfo
  * \since This struct is available since SDL 3.2.0.
  *
  * \sa SDL_CreateGPUComputePipeline
+ * \sa SDL_GPUShaderFormat
  */
 typedef struct SDL_GPUComputePipelineCreateInfo
 {
@@ -2104,7 +2126,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties(
  * \sa SDL_DestroyGPUDevice
  * \sa SDL_GPUSupportsShaderFormats
  */
-extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice(
+extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice(
     SDL_GPUShaderFormat format_flags,
     bool debug_mode,
     const char *name);
@@ -2152,7 +2174,7 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice(
  * \sa SDL_DestroyGPUDevice
  * \sa SDL_GPUSupportsProperties
  */
-extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties(
+extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties(
     SDL_PropertiesID props);
 
 #define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN          "SDL.gpu.device.create.debugmode"
@@ -2275,7 +2297,7 @@ extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUD
  * \sa SDL_BindGPUComputePipeline
  * \sa SDL_ReleaseGPUComputePipeline
  */
-extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline(
+extern SDL_DECLSPEC SDL_GPUComputePipeline * SDLCALL SDL_CreateGPUComputePipeline(
     SDL_GPUDevice *device,
     const SDL_GPUComputePipelineCreateInfo *createinfo);
 
@@ -2302,7 +2324,7 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline
  * \sa SDL_BindGPUGraphicsPipeline
  * \sa SDL_ReleaseGPUGraphicsPipeline
  */
-extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline(
+extern SDL_DECLSPEC SDL_GPUGraphicsPipeline * SDLCALL SDL_CreateGPUGraphicsPipeline(
     SDL_GPUDevice *device,
     const SDL_GPUGraphicsPipelineCreateInfo *createinfo);
 
@@ -2329,7 +2351,7 @@ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeli
  * \sa SDL_BindGPUFragmentSamplers
  * \sa SDL_ReleaseGPUSampler
  */
-extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler(
+extern SDL_DECLSPEC SDL_GPUSampler * SDLCALL SDL_CreateGPUSampler(
     SDL_GPUDevice *device,
     const SDL_GPUSamplerCreateInfo *createinfo);
 
@@ -2408,7 +2430,7 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler(
  * \sa SDL_CreateGPUGraphicsPipeline
  * \sa SDL_ReleaseGPUShader
  */
-extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader(
+extern SDL_DECLSPEC SDL_GPUShader * SDLCALL SDL_CreateGPUShader(
     SDL_GPUDevice *device,
     const SDL_GPUShaderCreateInfo *createinfo);
 
@@ -2469,7 +2491,7 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader(
  * \sa SDL_ReleaseGPUTexture
  * \sa SDL_GPUTextureSupportsFormat
  */
-extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture(
+extern SDL_DECLSPEC SDL_GPUTexture * SDLCALL SDL_CreateGPUTexture(
     SDL_GPUDevice *device,
     const SDL_GPUTextureCreateInfo *createinfo);
 
@@ -2490,6 +2512,10 @@ 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.
  *
+ * If you use a STORAGE flag, the data in the buffer must respect std140
+ * layout conventions. In practical terms this means you must ensure that vec3
+ * and vec4 fields are 16-byte aligned.
+ *
  * 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/)
@@ -2521,7 +2547,7 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture(
  * \sa SDL_DispatchGPUComputeIndirect
  * \sa SDL_ReleaseGPUBuffer
  */
-extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer(
+extern SDL_DECLSPEC SDL_GPUBuffer * SDLCALL SDL_CreateGPUBuffer(
     SDL_GPUDevice *device,
     const SDL_GPUBufferCreateInfo *createinfo);
 
@@ -2554,7 +2580,7 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer(
  * \sa SDL_DownloadFromGPUTexture
  * \sa SDL_ReleaseGPUTransferBuffer
  */
-extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer(
+extern SDL_DECLSPEC SDL_GPUTransferBuffer * SDLCALL SDL_CreateGPUTransferBuffer(
     SDL_GPUDevice *device,
     const SDL_GPUTransferBufferCreateInfo *createinfo);
 
@@ -2782,7 +2808,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline(
  * \sa SDL_SubmitGPUCommandBuffer
  * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
  */
-extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer(
+extern SDL_DECLSPEC SDL_GPUCommandBuffer * SDLCALL SDL_AcquireGPUCommandBuffer(
     SDL_GPUDevice *device);
 
 /* Uniform Data */
@@ -2792,6 +2818,10 @@ extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer(
  *
  * Subsequent draw calls will use this uniform data.
  *
+ * The data being pushed must respect std140 layout conventions. In practical
+ * terms this means you must ensure that vec3 and vec4 fields are 16-byte
+ * aligned.
+ *
  * \param command_buffer a command buffer.
  * \param slot_index the vertex uniform slot to push data to.
  * \param data client data to write.
@@ -2810,6 +2840,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData(
  *
  * Subsequent draw calls will use this uniform data.
  *
+ * The data being pushed must respect std140 layout conventions. In practical
+ * terms this means you must ensure that vec3 and vec4 fields are 16-byte
+ * aligned.
+ *
  * \param command_buffer a command buffer.
  * \param slot_index the fragment uniform slot to push data to.
  * \param data client data to write.
@@ -2828,6 +2862,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData(
  *
  * Subsequent draw calls will use this uniform data.
  *
+ * The data being pushed must respect std140 layout conventions. In practical
+ * terms this means you must ensure that vec3 and vec4 fields are 16-byte
+ * aligned.
+ *
  * \param command_buffer a command buffer.
  * \param slot_index the uniform slot to push data to.
  * \param data client data to write.
@@ -2868,7 +2906,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData(
  *
  * \sa SDL_EndGPURenderPass
  */
-extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass(
+extern SDL_DECLSPEC SDL_GPURenderPass * SDLCALL SDL_BeginGPURenderPass(
     SDL_GPUCommandBuffer *command_buffer,
     const SDL_GPUColorTargetInfo *color_target_infos,
     Uint32 num_color_targets,
@@ -2978,6 +3016,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer(
  *
  * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param render_pass a render pass handle.
  * \param first_slot the vertex sampler slot to begin binding from.
  * \param texture_sampler_bindings an array of texture-sampler binding
@@ -2986,6 +3027,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer(
  *                     array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers(
     SDL_GPURenderPass *render_pass,
@@ -2999,12 +3042,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers(
  * These textures must have been created with
  * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param render_pass a render pass handle.
  * \param first_slot the vertex storage texture slot to begin binding from.
  * \param storage_textures an array of storage textures.
  * \param num_bindings the number of storage texture to bind from the array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures(
     SDL_GPURenderPass *render_pass,
@@ -3018,12 +3066,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures(
  * These buffers must have been created with
  * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param render_pass a render pass handle.
  * \param first_slot the vertex storage buffer slot to begin binding from.
  * \param storage_buffers an array of buffers.
  * \param num_bindings the number of buffers to bind from the array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers(
     SDL_GPURenderPass *render_pass,
@@ -3036,6 +3089,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers(
  *
  * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param render_pass a render pass handle.
  * \param first_slot the fragment sampler slot to begin binding from.
  * \param texture_sampler_bindings an array of texture-sampler binding
@@ -3044,6 +3100,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers(
  *                     array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers(
     SDL_GPURenderPass *render_pass,
@@ -3057,12 +3115,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers(
  * These textures must have been created with
  * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param render_pass a render pass handle.
  * \param first_slot the fragment storage texture slot to begin binding from.
  * \param storage_textures an array of storage textures.
  * \param num_bindings the number of storage textures to bind from the array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures(
     SDL_GPURenderPass *render_pass,
@@ -3076,12 +3139,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures(
  * These buffers must have been created with
  * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param render_pass a render pass handle.
  * \param first_slot the fragment storage buffer slot to begin binding from.
  * \param storage_buffers an array of storage buffers.
  * \param num_bindings the number of storage buffers to bind from the array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers(
     SDL_GPURenderPass *render_pass,
@@ -3245,7 +3313,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass(
  *
  * \sa SDL_EndGPUComputePass
  */
-extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass(
+extern SDL_DECLSPEC SDL_GPUComputePass * SDLCALL SDL_BeginGPUComputePass(
     SDL_GPUCommandBuffer *command_buffer,
     const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings,
     Uint32 num_storage_texture_bindings,
@@ -3269,6 +3337,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline(
  *
  * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param compute_pass a compute pass handle.
  * \param first_slot the compute sampler slot to begin binding from.
  * \param texture_sampler_bindings an array of texture-sampler binding
@@ -3277,6 +3348,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline(
  *                     array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers(
     SDL_GPUComputePass *compute_pass,
@@ -3290,12 +3363,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers(
  * These textures must have been created with
  * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param compute_pass a compute pass handle.
  * \param first_slot the compute storage texture slot to begin binding from.
  * \param storage_textures an array of storage textures.
  * \param num_bindings the number of storage textures to bind from the array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures(
     SDL_GPUComputePass *compute_pass,
@@ -3309,12 +3387,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures(
  * These buffers must have been created with
  * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ.
  *
+ * Be sure your shader is set up according to the requirements documented in
+ * SDL_CreateGPUShader().
+ *
  * \param compute_pass a compute pass handle.
  * \param first_slot the compute storage buffer slot to begin binding from.
  * \param storage_buffers an array of storage buffer binding structs.
  * \param num_bindings the number of storage buffers to bind from the array.
  *
  * \since This function is available since SDL 3.2.0.
+ *
+ * \sa SDL_CreateGPUShader
  */
 extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers(
     SDL_GPUComputePass *compute_pass,
@@ -3389,7 +3472,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass(
 /**
  * Maps a transfer buffer into application address space.
  *
- * You must unmap the transfer buffer before encoding upload commands.
+ * You must unmap the transfer buffer before encoding upload commands. The
+ * memory is owned by the graphics driver - do NOT call SDL_free() on the
+ * returned pointer.
  *
  * \param device a GPU context.
  * \param transfer_buffer a transfer buffer.
@@ -3399,7 +3484,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass(
  *
  * \since This function is available since SDL 3.2.0.
  */
-extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer(
+extern SDL_DECLSPEC void * SDLCALL SDL_MapGPUTransferBuffer(
     SDL_GPUDevice *device,
     SDL_GPUTransferBuffer *transfer_buffer,
     bool cycle);
@@ -3430,7 +3515,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer(
  *
  * \since This function is available since SDL 3.2.0.
  */
-extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass(
+extern SDL_DECLSPEC SDL_GPUCopyPass * SDLCALL SDL_BeginGPUCopyPass(
     SDL_GPUCommandBuffer *command_buffer);
 
 /**
@@ -3848,6 +3933,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain(
  * freed by the user. You MUST NOT call this function from any thread other
  * than the one that created the window.
  *
+ * The swapchain texture is write-only and cannot be used as a sampler or for
+ * another reading operation.
+ *
  * \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
@@ -3866,6 +3954,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain(
  *
  * \sa SDL_SubmitGPUCommandBuffer
  * \sa SDL_SubmitGPUCommandBufferAndAcquireFence
+ * \sa SDL_AcquireGPUSwapchainTexture
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture(
     SDL_GPUCommandBuffer *command_buffer,
@@ -3922,7 +4011,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer(
  * \sa SDL_SubmitGPUCommandBuffer
  * \sa SDL_ReleaseGPUFence
  */
-extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence(
+extern SDL_DECLSPEC SDL_GPUFence * SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence(
     SDL_GPUCommandBuffer *command_buffer);
 
 /**
@@ -4004,6 +4093,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence(
 /**
  * Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence.
  *
+ * You must not reference the fence after calling this function.
+ *
  * \param device a GPU context.
  * \param fence a fence.
  *
@@ -4054,7 +4145,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat(
  * \param device a GPU context.
  * \param format the texture format to check.
  * \param sample_count the sample count to check.
- * \returns a hardware-specific version of min(preferred, possible).
+ * \returns whether the sample count is supported for this texture format.
  *
  * \since This function is available since SDL 3.2.0.
  */