gpu: Document why VertexID/InstanceID builtins are unreliable

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.