From 09d7e134de70a5de5f6d2bf4e099fcdbdefc9500 Mon Sep 17 00:00:00 2001 From: aidanfnv Date: Wed, 14 May 2025 08:06:59 -0700 Subject: 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 Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com> --- docs/user-guide/a2-01-spirv-target-specific.md | 22 +++++++++++++++++++++- docs/user-guide/toc.html | 1 + 2 files changed, 22 insertions(+), 1 deletion(-) (limited to 'docs/user-guide') 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`** | `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 @@
  • Experimental support for the older versions of SPIR-V
  • Combined texture sampler
  • System-Value semantics
    • +
  • Using SV_InstanceID with SPIR-V target
  • Behavior of `discard` after SPIR-V 1.6
  • Supported HLSL features when targeting SPIR-V
  • Unsupported GLSL keywords when targeting SPIR-V
    • -- cgit v1.2.3