From 68038394d15e8ff87a152b2fc4c8c9a90e6850c5 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Thu, 29 Aug 2024 22:58:01 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
---
include/SDL3/SDL_gpu.h | 1181 +++++++++++++++++++++-----------------
include/SDL3/SDL_hints.h | 3 +-
2 files changed, 642 insertions(+), 542 deletions(-)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 3ac74d63ca518..df29b931a1d7c 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -20,7 +20,7 @@
*/
/**
- * \file SDL_gpu.h
+ * # CategoryGpu
*
* Include file for SDL GPU API functions
*/
@@ -921,13 +921,16 @@ typedef struct SDL_GpuStorageTextureWriteOnlyBinding
/**
* Creates a GPU context.
*
- * \param formatFlags a bitflag indicating which shader formats the app is able to provide
- * \param debugMode enable debug mode properties and validations
- * \param preferLowPower set this to SDL_TRUE if your app prefers energy efficiency over maximum GPU performance
- * \param name the preferred GPU driver, or NULL to let SDL pick the optimal driver
- * \returns a GPU context on success or NULL on failure
+ * \param formatFlags a bitflag indicating which shader formats the app is
+ * able to provide.
+ * \param debugMode enable debug mode properties and validations.
+ * \param preferLowPower set this to SDL_TRUE if your app prefers energy
+ * efficiency over maximum GPU performance.
+ * \param name the preferred GPU driver, or NULL to let SDL pick the optimal
+ * driver.
+ * \returns a GPU context on success or NULL on failure.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGpuDriver
* \sa SDL_DestroyGpuDevice
@@ -943,26 +946,34 @@ extern SDL_DECLSPEC SDL_GpuDevice *SDLCALL SDL_CreateGpuDevice(
*
* These are the supported properties:
*
- * - `SDL_PROP_GPU_CREATEDEVICE_DEBUGMODE_BOOL`: enable debug mode properties and validations, default is true
- * - `SDL_PROP_GPU_CREATEDEVICE_PREFERLOWPOWER_BOOL`: enable to prefer energy efficiency over maximum GPU performance
- * - `SDL_PROP_GPU_CREATEDEVICE_NAME_STRING`: the name of the GPU driver to use, if a specific one is desired
+ * - `SDL_PROP_GPU_CREATEDEVICE_DEBUGMODE_BOOL`: enable debug mode properties
+ * and validations, default is true
+ * - `SDL_PROP_GPU_CREATEDEVICE_PREFERLOWPOWER_BOOL`: enable to prefer energy
+ * efficiency over maximum GPU performance
+ * - `SDL_PROP_GPU_CREATEDEVICE_NAME_STRING`: the name of the GPU driver to
+ * use, if a specific one is desired
*
* These are the current shader format properties:
*
- * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_SECRET_BOOL`: The app is able to provide shaders for an NDA platform
- * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_SPIRV_BOOL`: The app is able to provide SPIR-V shaders if applicable
- * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_DXBC_BOOL`: The app is able to provide DXBC shaders if applicable
- * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_DXIL_BOOL`: The app is able to provide DXIL shaders if applicable
- * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_MSL_BOOL`: The app is able to provide MSL shaders if applicable
- * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_METALLIB_BOOL`: The app is able to provide Metal shader libraries if applicable
- *
- * With the D3D12 renderer:
- * - `SDL_PROP_GPU_CREATEDEVICE_D3D12_SEMANTIC_NAME_STRING`: the prefix to use for all vertex semantics, default is "TEXCOORD"
+ * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_SECRET_BOOL`: The app is able to provide
+ * shaders for an NDA platform `SDL_PROP_GPU_CREATEDEVICE_SHADERS_SPIRV_BOOL`:
+ * The app is able to provide SPIR-V shaders if applicable
+ * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_DXBC_BOOL`: The app is able to provide
+ * DXBC shaders if applicable `SDL_PROP_GPU_CREATEDEVICE_SHADERS_DXIL_BOOL`:
+ * The app is able to provide DXIL shaders if applicable
+ * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_MSL_BOOL`: The app is able to provide
+ * MSL shaders if applicable
+ * `SDL_PROP_GPU_CREATEDEVICE_SHADERS_METALLIB_BOOL`: The app is able to
+ * provide Metal shader libraries if applicable
+ *
+ * With the D3D12 renderer: -
+ * `SDL_PROP_GPU_CREATEDEVICE_D3D12_SEMANTIC_NAME_STRING`: the prefix to use
+ * for all vertex semantics, default is "TEXCOORD"
*
* \param props the properties to use.
- * \returns a GPU context on success or NULL on failure
+ * \returns a GPU context on success or NULL on failure.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGpuDriver
* \sa SDL_DestroyGpuDevice
@@ -984,9 +995,9 @@ extern SDL_DECLSPEC SDL_GpuDevice *SDLCALL SDL_CreateGpuDeviceWithProperties(
/**
* Destroys a GPU context previously returned by SDL_CreateGpuDevice.
*
- * \param device a GPU Context to destroy
+ * \param device a GPU Context to destroy.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateGpuDevice
*/
@@ -995,10 +1006,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyGpuDevice(SDL_GpuDevice *device);
/**
* Returns the backend used to create this GPU context.
*
- * \param device a GPU context to query
- * \returns an SDL_GpuDriver value, or SDL_GPU_DRIVER_INVALID on error
+ * \param device a GPU context to query.
+ * \returns an SDL_GpuDriver value, or SDL_GPU_DRIVER_INVALID on error.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC SDL_GpuDriver SDLCALL SDL_GetGpuDriver(SDL_GpuDevice *device);
@@ -1007,36 +1018,32 @@ extern SDL_DECLSPEC SDL_GpuDriver SDLCALL SDL_GetGpuDriver(SDL_GpuDevice *device
/**
* Creates a pipeline object to be used in a compute workflow.
*
- * Shader resource bindings must be authored to follow a particular order.
- * For SPIR-V shaders, use the following resource sets:
- * 0: Read-only storage textures, followed by read-only storage buffers
- * 1: Write-only storage textures, followed by write-only storage buffers
- * 2: Uniform buffers
- *
- * For DXBC Shader Model 5_0 shaders, use the following register order:
- * For t registers:
- * Read-only storage textures, followed by read-only storage buffers
- * For u registers:
- * Write-only storage textures, followed by write-only storage buffers
- * For b registers:
- * Uniform buffers
- *
- * For DXIL shaders, use the following register order:
- * (t[n], space0): Read-only storage textures, followed by read-only storage buffers
- * (u[n], space1): Write-only storage textures, followed by write-only storage buffers
- * (b[n], space2): Uniform buffers
- *
- * For MSL/metallib, use the following order:
- * For [[buffer]]:
- * Uniform buffers, followed by write-only storage buffers, followed by write-only storage buffers
- * For [[texture]]:
- * Read-only storage textures, followed by write-only storage textures
- *
- * \param device a GPU Context
- * \param computePipelineCreateInfo a struct describing the state of the requested compute pipeline
- * \returns a compute pipeline object on success, or NULL on failure
- *
- * \since This function is available since SDL 3.x.x
+ * Shader resource bindings must be authored to follow a particular order. For
+ * SPIR-V shaders, use the following resource sets: 0: Read-only storage
+ * textures, followed by read-only storage buffers 1: Write-only storage
+ * textures, followed by write-only storage buffers 2: Uniform buffers
+ *
+ * For DXBC Shader Model 5_0 shaders, use the following register order: For t
+ * registers: Read-only storage textures, followed by read-only storage
+ * buffers For u registers: Write-only storage textures, followed by
+ * write-only storage buffers For b registers: Uniform buffers
+ *
+ * For DXIL shaders, use the following register order: (t[n], space0):
+ * Read-only storage textures, followed by read-only storage buffers (u[n],
+ * space1): Write-only storage textures, followed by write-only storage
+ * buffers (b[n], space2): Uniform buffers
+ *
+ * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers,
+ * followed by write-only storage buffers, followed by write-only storage
+ * buffers For [[texture]]: Read-only storage textures, followed by write-only
+ * storage textures
+ *
+ * \param device a GPU Context.
+ * \param computePipelineCreateInfo a struct describing the state of the
+ * requested compute pipeline.
+ * \returns a compute pipeline object on success, or NULL on failure.
+ *
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_BindGpuComputePipeline
* \sa SDL_ReleaseGpuComputePipeline
@@ -1048,11 +1055,12 @@ extern SDL_DECLSPEC SDL_GpuComputePipeline *SDLCALL SDL_CreateGpuComputePipeline
/**
* Creates a pipeline object to be used in a graphics workflow.
*
- * \param device a GPU Context
- * \param pipelineCreateInfo a struct describing the state of the desired graphics pipeline
- * \returns a graphics pipeline object on success, or NULL on failure
+ * \param device a GPU Context.
+ * \param pipelineCreateInfo a struct describing the state of the desired
+ * graphics pipeline.
+ * \returns a graphics pipeline object on success, or NULL on failure.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateGpuShader
* \sa SDL_BindGpuGraphicsPipeline
@@ -1063,13 +1071,15 @@ extern SDL_DECLSPEC SDL_GpuGraphicsPipeline *SDLCALL SDL_CreateGpuGraphicsPipeli
SDL_GpuGraphicsPipelineCreateInfo *pipelineCreateInfo);
/**
- * Creates a sampler object to be used when binding textures in a graphics workflow.
+ * Creates a sampler object to be used when binding textures in a graphics
+ * workflow.
*
- * \param device a GPU Context
- * \param samplerCreateInfo a struct describing the state of the desired sampler
- * \returns a sampler object on success, or NULL on failure
+ * \param device a GPU Context.
+ * \param samplerCreateInfo a struct describing the state of the desired
+ * sampler.
+ * \returns a sampler object on success, or NULL on failure.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_BindGpuVertexSamplers
* \sa SDL_BindGpuFragmentSamplers
@@ -1085,48 +1095,39 @@ extern SDL_DECLSPEC SDL_GpuSampler *SDLCALL SDL_CreateGpuSampler(
* Shader resource bindings must be authored to follow a particular order
* depending on the shader format.
*
- * For SPIR-V shaders, use the following resource sets:
- * For vertex shaders:
- * 0: Sampled textures, followed by storage textures, followed by storage buffers
- * 1: Uniform buffers
- * For fragment shaders:
- * 2: Sampled textures, followed by storage textures, followed by storage buffers
- * 3: Uniform buffers
- *
- * For DXBC Shader Model 5_0 shaders, use the following register order:
- * For t registers:
- * Sampled textures, followed by storage textures, followed by storage buffers
- * For s registers:
- * Samplers with indices corresponding to the sampled textures
- * For b registers:
- * Uniform buffers
- *
- * For DXIL shaders, use the following register order:
- * For vertex shaders:
- * (t[n], space0): Sampled textures, followed by storage textures, followed by storage buffers
- * (s[n], space0): Samplers with indices corresponding to the sampled textures
- * (b[n], space1): Uniform buffers
- * For pixel shaders:
- * (t[n], space2): Sampled textures, followed by storage textures, followed by storage buffers
- * (s[n], space2): Samplers with indices corresponding to the sampled textures
- * (b[n], space3): Uniform buffers
- *
- * For MSL/metallib, use the following order:
- * For [[texture]]:
- * Sampled textures, followed by storage textures
- * For [[sampler]]:
- * Samplers with indices corresponding to the sampled textures
- * For [[buffer]]:
- * Uniform buffers, followed by storage buffers.
- * Vertex buffer 0 is bound at [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on.
- * Rather than manually authoring vertex buffer indices, use the [[stage_in]] attribute
- * which will automatically use the vertex input information from the SDL_GpuPipeline.
- *
- * \param device a GPU Context
- * \param shaderCreateInfo a struct describing the state of the desired shader
- * \returns a shader object on success, or NULL on failure
- *
- * \since This function is available since SDL 3.x.x
+ * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0:
+ * Sampled textures, followed by storage textures, followed by storage buffers
+ * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by
+ * storage textures, followed by storage buffers 3: Uniform buffers
+ *
+ * For DXBC Shader Model 5_0 shaders, use the following register order: For t
+ * registers: Sampled textures, followed by storage textures, followed by
+ * storage buffers For s registers: Samplers with indices corresponding to the
+ * sampled textures For b registers: Uniform buffers
+ *
+ * For DXIL shaders, use the following register order: For vertex shaders:
+ * (t[n], space0): Sampled textures, followed by storage textures, followed by
+ * storage buffers (s[n], space0): Samplers with indices corresponding to the
+ * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n],
+ * space2): Sampled textures, followed by storage textures, followed by
+ * storage buffers (s[n], space2): Samplers with indices corresponding to the
+ * sampled textures (b[n], space3): Uniform buffers
+ *
+ * For MSL/metallib, use the following order: For [[texture]]: Sampled
+ * textures, followed by storage textures For [[sampler]]: Samplers with
+ * indices corresponding to the sampled textures For [[buffer]]: Uniform
+ * buffers, followed by storage buffers. Vertex buffer 0 is bound at
+ * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than
+ * manually authoring vertex buffer indices, use the [[stage_in]] attribute
+ * which will automatically use the vertex input information from the
+ * SDL_GpuPipeline.
+ *
+ * \param device a GPU Context.
+ * \param shaderCreateInfo a struct describing the state of the desired
+ * shader.
+ * \returns a shader object on success, or NULL on failure.
+ *
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateGpuGraphicsPipeline
* \sa SDL_ReleaseGpuShader
@@ -1137,19 +1138,23 @@ extern SDL_DECLSPEC SDL_GpuShader *SDLCALL SDL_CreateGpuShader(
/**
* Creates a texture object to be used in graphics or compute workflows.
- * The contents of this texture are undefined until data is written to the texture.
*
- * Note that certain combinations of usage flags are invalid.
- * For example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags.
+ * The contents of this texture are undefined until data is written to the
+ * texture.
*
- * If you request a sample count higher than the hardware supports,
- * the implementation will automatically fall back to the highest available sample count.
+ * Note that certain combinations of usage flags are invalid. For example, a
+ * texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags.
*
- * \param device a GPU Context
- * \param textureCreateInfo a struct describing the state of the texture to create
- * \returns a texture object on success, or NULL on failure
+ * If you request a sample count higher than the hardware supports, the
+ * implementation will automatically fall back to the highest available sample
+ * count.
*
- * \since This function is available since SDL 3.x.x
+ * \param device a GPU Context.
+ * \param textureCreateInfo a struct describing the state of the texture to
+ * create.
+ * \returns a texture object on success, or NULL on failure.
+ *
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_UploadToGpuTexture
* \sa SDL_DownloadFromGpuTexture
@@ -1168,16 +1173,19 @@ extern SDL_DECLSPEC SDL_GpuTexture *SDLCALL SDL_CreateGpuTexture(
/**
* Creates a buffer object to be used in graphics or compute workflows.
- * The contents of this buffer are undefined until data is written to the buffer.
*
- * Note that certain combinations of usage flags are invalid.
- * For example, a buffer cannot have both the VERTEX and INDEX flags.
+ * The contents of this buffer are undefined until data is written to the
+ * buffer.
*
- * \param device a GPU Context
- * \param bufferCreateInfo a struct describing the state of the buffer to create
- * \returns a buffer object on success, or NULL on failure
+ * Note that certain combinations of usage flags are invalid. For example, a
+ * buffer cannot have both the VERTEX and INDEX flags.
*
- * \since This function is available since SDL 3.x.x
+ * \param device a GPU Context.
+ * \param bufferCreateInfo a struct describing the state of the buffer to
+ * create.
+ * \returns a buffer object on success, or NULL on failure.
+ *
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_UploadToGpuBuffer
* \sa SDL_BindGpuVertexBuffers
@@ -1192,13 +1200,15 @@ extern SDL_DECLSPEC SDL_GpuBuffer *SDLCALL SDL_CreateGpuBuffer(
SDL_GpuBufferCreateInfo *bufferCreateInfo);
/**
- * Creates a transfer buffer to be used when uploading to or downloading from graphics resources.
+ * Creates a transfer buffer to be used when uploading to or downloading from
+ * graphics resources.
*
- * \param device a GPU Context
- * \param transferBufferCreateInfo a struct describing the state of the transfer buffer to create
- * \returns a transfer buffer on success, or NULL on failure
+ * \param device a GPU Context.
+ * \param transferBufferCreateInfo a struct describing the state of the
+ * transfer buffer to create.
+ * \returns a transfer buffer on success, or NULL on failure.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_UploadToGpuBuffer
* \sa SDL_DownloadFromGpuBuffer
@@ -1213,13 +1223,15 @@ extern SDL_DECLSPEC SDL_GpuTransferBuffer *SDLCALL SDL_CreateGpuTransferBuffer(
/* Debug Naming */
/**
- * Sets an arbitrary string constant to label a buffer. Useful for debugging.
+ * Sets an arbitrary string constant to label a buffer.
*
- * \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
+ * Useful for debugging.
+ *
+ * \param device a GPU Context.
+ * \param buffer a buffer to attach the name to.
+ * \param text a UTF-8 string constant to mark as the name of the buffer.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_SetGpuBufferName(
SDL_GpuDevice *device,
@@ -1227,13 +1239,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGpuBufferName(
const char *text);
/**
- * Sets an arbitrary string constant to label a texture. Useful for debugging.
+ * Sets an arbitrary string constant to label a texture.
+ *
+ * Useful for debugging.
*
- * \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
+ * \param device a GPU Context.
+ * \param texture a texture to attach the name to.
+ * \param text a UTF-8 string constant to mark as the name of the texture.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_SetGpuTextureName(
SDL_GpuDevice *device,
@@ -1242,12 +1256,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGpuTextureName(
/**
* Inserts an arbitrary string label into the command buffer callstream.
+ *
* Useful for debugging.
*
- * \param commandBuffer a command buffer
- * \param text a UTF-8 string constant to insert as the label
+ * \param commandBuffer a command buffer.
+ * \param text a UTF-8 string constant to insert as the label.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_InsertGpuDebugLabel(
SDL_GpuCommandBuffer *commandBuffer,
@@ -1255,19 +1270,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_InsertGpuDebugLabel(
/**
* Begins a debug group with an arbitary name.
- * Used for denoting groups of calls when viewing the command buffer callstream
- * in a graphics debugging tool.
*
- * Each call to SDL_PushGpuDebugGroup must have a corresponding call to SDL_PopGpuDebugGroup.
+ * Used for denoting groups of calls when viewing the command buffer
+ * callstream in a graphics debugging tool.
*
- * On some backends (e.g. Metal), pushing a debug group during a render/blit/compute pass
- * will create a group that is scoped to the native pass rather than the command buffer.
- * For best results, if you push a debug group during a pass, always pop it in the same pass.
+ * Each call to SDL_PushGpuDebugGroup must have a corresponding call to
+ * SDL_PopGpuDebugGroup.
*
- * \param commandBuffer a command buffer
- * \param name a UTF-8 string constant that names the group
+ * On some backends (e.g. Metal), pushing a debug group during a
+ * render/blit/compute pass will create a group that is scoped to the native
+ * pass rather than the command buffer. For best results, if you push a debug
+ * group during a pass, always pop it in the same pass.
*
- * \since This function is available since SDL 3.x.x
+ * \param commandBuffer a command buffer.
+ * \param name a UTF-8 string constant that names the group.
+ *
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_PopGpuDebugGroup
*/
@@ -1278,9 +1296,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGpuDebugGroup(
/**
* Ends the most-recently pushed debug group.
*
- * \param commandBuffer a command buffer
+ * \param commandBuffer a command buffer.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_PushGpuDebugGroup
*/
@@ -1291,12 +1309,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_PopGpuDebugGroup(
/**
* Frees the given texture as soon as it is safe to do so.
+ *
* You must not reference the texture after calling this function.
*
- * \param device a GPU context
- * \param texture a texture to be destroyed
+ * \param device a GPU context.
+ * \param texture a texture to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuTexture(
SDL_GpuDevice *device,
@@ -1304,12 +1323,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuTexture(
/**
* Frees the given sampler as soon as it is safe to do so.
+ *
* You must not reference the texture after calling this function.
*
- * \param device a GPU context
- * \param sampler a sampler to be destroyed
+ * \param device a GPU context.
+ * \param sampler a sampler to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuSampler(
SDL_GpuDevice *device,
@@ -1317,12 +1337,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuSampler(
/**
* Frees the given buffer as soon as it is safe to do so.
+ *
* You must not reference the buffer after calling this function.
*
- * \param device a GPU context
- * \param buffer a buffer to be destroyed
+ * \param device a GPU context.
+ * \param buffer a buffer to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuBuffer(
SDL_GpuDevice *device,
@@ -1330,12 +1351,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuBuffer(
/**
* Frees the given transfer buffer as soon as it is safe to do so.
+ *
* You must not reference the transfer buffer after calling this function.
*
- * \param device a GPU context
- * \param transferBuffer a transfer buffer to be destroyed
+ * \param device a GPU context.
+ * \param transferBuffer a transfer buffer to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuTransferBuffer(
SDL_GpuDevice *device,
@@ -1343,12 +1365,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuTransferBuffer(
/**
* Frees the given compute pipeline as soon as it is safe to do so.
+ *
* You must not reference the compute pipeline after calling this function.
*
- * \param device a GPU context
- * \param computePipeline a compute pipeline to be destroyed
+ * \param device a GPU context.
+ * \param computePipeline a compute pipeline to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuComputePipeline(
SDL_GpuDevice *device,
@@ -1356,12 +1379,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuComputePipeline(
/**
* Frees the given shader as soon as it is safe to do so.
+ *
* You must not reference the shader after calling this function.
*
- * \param device a GPU context
- * \param shader a shader to be destroyed
+ * \param device a GPU context.
+ * \param shader a shader to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuShader(
SDL_GpuDevice *device,
@@ -1369,12 +1393,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuShader(
/**
* Frees the given graphics pipeline as soon as it is safe to do so.
+ *
* You must not reference the graphics pipeline after calling this function.
*
- * \param device a GPU context
- * \param graphicsPipeline a graphics pipeline to be destroyed
+ * \param device a GPU context.
+ * \param graphicsPipeline a graphics pipeline to be destroyed.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuGraphicsPipeline(
SDL_GpuDevice *device,
@@ -1398,14 +1423,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGpuGraphicsPipeline(
/**
* Acquire a command buffer.
- * This command buffer is managed by the implementation and should not be freed by the user.
- * The command buffer may only be used on the thread it was acquired on.
- * The command buffer should be submitted on the thread it was acquired on.
*
- * \param device a GPU context
- * \returns a command buffer
+ * This command buffer is managed by the implementation and should not be
+ * freed by the user. The command buffer may only be used on the thread it was
+ * acquired on. The command buffer should be submitted on the thread it was
+ * acquired on.
+ *
+ * \param device a GPU context.
+ * \returns a command buffer.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*
* \sa SDL_SubmitGpu
* \sa SDL_SubmitGpuAndAcquireFence
@@ -1435,14 +1462,15 @@ extern SDL_DECLSPEC SDL_GpuCommandBuffer *SDLCALL SDL_AcquireGpuCommandBuffer(
/**
* Pushes data to a vertex uniform slot on the command buffer.
+ *
* Subsequent draw calls will use this uniform data.
*
- * \param commandBuffer a command buffer
- * \param slotIndex the vertex uniform slot to push data to
- * \param data client data to write
- * \param dataLengthInBytes the length of the data to write
+ * \param commandBuffer a command buffer.
+ * \param slotIndex the vertex uniform slot to push data to.
+ * \param data client data to write.
+ * \param dataLengthInBytes the length of the data to write.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_PushGpuVertexUniformData(
SDL_GpuCommandBuffer *commandBuffer,
@@ -1452,14 +1480,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGpuVertexUniformData(
/**
* Pushes data to a fragment uniform slot on the command buffer.
+ *
* Subsequent draw calls will use this uniform data.
*
- * \param commandBuffer a command buffer
- * \param slotIndex the fragment uniform slot to push data to
- * \param data client data to write
- * \param dataLengthInBytes the length of the data to write
+ * \param commandBuffer a command buffer.
+ * \param slotIndex the fragment uniform slot to push data to.
+ * \param data client data to write.
+ * \param dataLengthInBytes the length of the data to write.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_PushGpuFragmentUniformData(
SDL_GpuCommandBuffer *commandBuffer,
@@ -1469,14 +1498,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGpuFragmentUniformData(
/**
* Pushes data to a uniform slot on the command buffer.
+ *
* Subsequent draw calls will use this uniform data.
*
- * \param commandBuffer a command buffer
- * \param slotIndex the uniform slot to push data to
- * \param data client data to write
- * \param dataLengthInBytes the length of the data to write
+ * \param commandBuffer a command buffer.
+ * \param slotIndex the uniform slot to push data to.
+ * \param data client data to write.
+ * \param dataLengthInBytes the length of the data to write.
*
- * \since This function is available since SDL 3.x.x
+ * \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_PushGpuComputeUniformData(
SDL_GpuCommandBuffer *commandBuffer,
@@ -1527,21 +1557,26 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGpuComputeUniformData(
/**
* Begins a render pass on a command buffer.
- * A render pass consists of a set of texture subresources (or depth slices in the 3D texture case)
- * which will be rendered to during the render pass,
- * along with corresponding clear values and load/store operations.
- * All operations related to graphics pipelines must take place inside of a render pass.
- * A default viewport and scissor state are automatically set when this is called.
- * You cannot begin another render pass, or begin a compute pass or copy pass
- * until you have ended the render pass.
- *
- * \param commandBuffer a command buffer
- * \param colorAttachmentInfos an array of texture subresources with corresponding clear values and load/store ops
- * \param colorAttachmentCount the number of color attachments in the colorAttachmentInfos array
- * \param depthStencilAttachmentInfo a texture subresource with corresponding clear value and load/store ops, may be NULL
- * \returns a render pass handle
- *
- * \since This function is available since SDL 3.x.x
+ *
+ * A render pass consists of a set of texture subresources (or depth slices in
+ * the 3D texture case) which will be rendered to during the render pass,
+ * along with corresponding clear values and load/store operations. All
+ * operations related to graphics pipelines must take place inside of a render
+ * pass. A default viewport and scissor sta
(Patch may be truncated, please check the link at the top of this post.)