From 65e0fed5b3099b9faaab5d7f2114f13af8194204 Mon Sep 17 00:00:00 2001
From: Ethan Lee <flibitijibibo@gmail.com>
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 305b1165ba..ed4df13cbf 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.