From 65e0fed5b3099b9faaab5d7f2114f13af8194204 Mon Sep 17 00:00:00 2001
From: Ethan Lee <[EMAIL REDACTED]>
Date: Tue, 24 Dec 2024 14:52:32 -0500
Subject: [PATCH] gpu: Document why VertexID/InstanceID builtins are unreliable
---
include/SDL3/SDL_gpu.h | 24 ++++++++++++++++--------
1 file changed, 16 insertions(+), 8 deletions(-)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 305b1165ba2a1..ed4df13cbf33d 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -1419,8 +1419,10 @@ typedef struct SDL_GPUBufferRegion
*
* Note that the `first_vertex` and `first_instance` parameters are NOT
* compatible with built-in vertex/instance ID variables in shaders (for
- * example, SV_VertexID). If your shader depends on these variables, the
- * correlating draw call parameter MUST be 0.
+ * example, SV_VertexID); GPU APIs and shader languages do not define these
+ * built-in variables consistently, so if your shader depends on them, the only
+ * way to keep behavior consistent and portable is to always pass 0 for the
+ * correlating parameter in the draw calls.
*
* \since This struct is available since SDL 3.1.3
*
@@ -1439,8 +1441,10 @@ typedef struct SDL_GPUIndirectDrawCommand
*
* Note that the `first_vertex` and `first_instance` parameters are NOT
* compatible with built-in vertex/instance ID variables in shaders (for
- * example, SV_VertexID). If your shader depends on these variables, the
- * correlating draw call parameter MUST be 0.
+ * example, SV_VertexID); GPU APIs and shader languages do not define these
+ * built-in variables consistently, so if your shader depends on them, the only
+ * way to keep behavior consistent and portable is to always pass 0 for the
+ * correlating parameter in the draw calls.
*
* \since This struct is available since SDL 3.1.3
*
@@ -3025,8 +3029,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers(
*
* Note that the `first_vertex` and `first_instance` parameters are NOT
* compatible with built-in vertex/instance ID variables in shaders (for
- * example, SV_VertexID). If your shader depends on these variables, the
- * correlating draw call parameter MUST be 0.
+ * example, SV_VertexID); GPU APIs and shader languages do not define these
+ * built-in variables consistently, so if your shader depends on them, the only
+ * way to keep behavior consistent and portable is to always pass 0 for the
+ * correlating parameter in the draw calls.
*
* \param render_pass a render pass handle.
* \param num_indices the number of indices to draw per instance.
@@ -3053,8 +3059,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives(
*
* Note that the `first_vertex` and `first_instance` parameters are NOT
* compatible with built-in vertex/instance ID variables in shaders (for
- * example, SV_VertexID). If your shader depends on these variables, the
- * correlating draw call parameter MUST be 0.
+ * example, SV_VertexID); GPU APIs and shader languages do not define these
+ * built-in variables consistently, so if your shader depends on them, the only
+ * way to keep behavior consistent and portable is to always pass 0 for the
+ * correlating parameter in the draw calls.
*
* \param render_pass a render pass handle.
* \param num_vertices the number of vertices to draw.