Add explanation for SV_InstanceID usage difference from SPIR-V (#7072)

Closes https://github.com/shader-slang/slang/issues/6805

This change adds a note to the SPIR-V target specific doc that SV_InstanceID does not map directly to SPIR-V's BuiltIn InstanceIndex, and adds a more detailed explanation of the difference, its motivation, and how to derive the actual value equivalent to BuiltIn InstanceIndex with an example.

---------

Co-authored-by: slangbot <ellieh+slangbot@nvidia.com>
Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

2 files changed, 22 insertions, 1 deletions

diff --git a/docs/user-guide/a2-01-spirv-target-specific.md b/docs/user-guide/a2-01-spirv-target-specific.md
index 2ea4372d9..4bdac1953 100644
--- a/docs/user-guide/a2-01-spirv-target-specific.md
+++ b/docs/user-guide/a2-01-spirv-target-specific.md
@@ -57,7 +57,7 @@ The system-value semantics are translated to the following SPIR-V code.
 | `SV_GroupThreadID`            | `BuiltIn LocalInvocationId`       |
 | `SV_InnerCoverage`            | `BuiltIn FullyCoveredEXT`         |
 | `SV_InsideTessFactor`         | `BuiltIn TessLevelInner`          |
-| `SV_InstanceID`               | `BuiltIn InstanceIndex`           |
+| `SV_InstanceID`<sup>**</sup>  | `BuiltIn InstanceIndex`           |
 | `SV_IntersectionAttributes`   | *Not supported*                   |
 | `SV_IsFrontFace`              | `BuiltIn FrontFacing`             |
 | `SV_OutputControlPointID`     | `BuiltIn InvocationId`            |
@@ -78,7 +78,27 @@ The system-value semantics are translated to the following SPIR-V code.
 | `SV_ViewportArrayIndex`       | `BuiltIn ViewportIndex`           |
 
 *Note* that `SV_DrawIndex`, `SV_PointSize` and `SV_PointCoord` are Slang-specific semantics that are not defined in HLSL.
+Also *Note* that `SV_InstanceID` counts all instances in a draw call, unlike how `InstanceIndex` is relative to `BaseInstance`. See [Using SV_InstanceID with SPIR-V target](#using-sv_instanceid-with-spir-v-target)
 
+Using SV_InstanceID with SPIR-V target
+--------------------------------------
+
+When using `SV_InstanceID` with SPIR-V target, it is equivalent to the difference between the `InstanceIndex` and `BaseInstance` builtins.
+This matches the behavior of D3D where `SV_InstanceID` starts from zero for each draw call, while in SPIR-V, `InstanceIndex` includes the base instance.
+
+If you need direct access to the `InstanceIndex` value, you can use parameters with `SV_InstanceID` and `SV_StartInstanceLocation` semantics:
+
+```slang
+void myVertexShader(
+    uint instanceID : SV_InstanceID,               // InstanceIndex - BaseInstance
+    uint baseInstance : SV_StartInstanceLocation)   // BaseInstance
+{
+    // If you need InstanceIndex, just add them:
+    uint instanceIndex = instanceID + baseInstance;
+
+    // Use instanceID, baseInstance, or instanceIndex as needed
+}
+```
 
 Behavior of `discard` after SPIR-V 1.6
 --------------------------------------
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index 13f6e9f03..a60780e65 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -194,6 +194,7 @@
 <li data-link="spirv-target-specific#experimental-support-for-the-older-versions-of-spir-v"><span>Experimental support for the older versions of SPIR-V</span></li>
 <li data-link="spirv-target-specific#combined-texture-sampler"><span>Combined texture sampler</span></li>
 <li data-link="spirv-target-specific#system-value-semantics"><span>System-Value semantics</span></li>
+<li data-link="spirv-target-specific#using-sv_instanceid-with-spir-v-target"><span>Using SV_InstanceID with SPIR-V target</span></li>
 <li data-link="spirv-target-specific#behavior-of-discard-after-spir-v-16"><span>Behavior of `discard` after SPIR-V 1.6</span></li>
 <li data-link="spirv-target-specific#supported-hlsl-features-when-targeting-spir-v"><span>Supported HLSL features when targeting SPIR-V</span></li>
 <li data-link="spirv-target-specific#unsupported-glsl-keywords-when-targeting-spir-v"><span>Unsupported GLSL keywords when targeting SPIR-V</span></li>