From 8df17c97d146b6a8bd7fcfb557bda499ae5a096e Mon Sep 17 00:00:00 2001
From: cosmonaut <[EMAIL REDACTED]>
Date: Fri, 24 Jan 2025 12:04:00 -0800
Subject: [PATCH] GPU: Add notes about shader resource requirements to
documentation
---
include/SDL3/SDL_gpu.h | 36 ++++++++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 854f53d11bb72..b13641130596e 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -2999,6 +2999,8 @@ 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
@@ -3007,6 +3009,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,
@@ -3020,12 +3024,16 @@ 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,
@@ -3039,12 +3047,16 @@ 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,
@@ -3057,6 +3069,8 @@ 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
@@ -3065,6 +3079,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,
@@ -3078,12 +3094,16 @@ 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,
@@ -3097,12 +3117,16 @@ 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,
@@ -3290,6 +3314,8 @@ 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
@@ -3298,6 +3324,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,
@@ -3311,12 +3339,16 @@ 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,
@@ -3330,12 +3362,16 @@ 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,