Semantics
A semantic is a string attached to a shader input or output that conveys information about the intended use of a parameter. Semantics are required on all variables passed between shader stages. The syntax for adding a semantic to a shader variable is shown here (Variable Syntax (DirectX HLSL)).
In general, data passed between pipeline stages is completely generic and is not uniquely interpreted by the system; arbitrary semantics are allowed which have no special meaning. Parameters (in Direct3D 10 and later) which contain these special semantics are referred to as System-Value Semantics.
Semantics Supported in Direct3D 9 and Direct3D 10 and later
The following types of semantics are supported in both Direct3D 9 and Direct3D 10 and later.
Vertex Shader Semantics
These semantics have meaning when attached to a vertex-shader parameter. These semantics are supported in both Direct3D 9 and Direct3D 10 and later.
| Input | Description | Type |
|---|---|---|
| BINORMAL[n] | Binormal | float4 |
| BLENDINDICES[n] | Blend indices | uint |
| BLENDWEIGHT[n] | Blend weights | float |
| COLOR[n] | Diffuse and specular color | float4 |
| NORMAL[n] | Normal vector | float4 |
| POSITION[n] | Vertex position in object space. | float4 |
| POSITIONT | Transformed vertex position. | float4 |
| PSIZE[n] | Point size | float |
| TANGENT[n] | Tangent | float4 |
| TEXCOORD[n] | Texture coordinates | float4 |
| Output | Description | Type |
|---|---|---|
| COLOR[n] | Diffuse or specular color | float4 |
| FOG | Vertex fog | float |
| POSITION[n] | Position of a vertex in homogenous space. Compute position in screen-space by dividing (x,y,z) by w. Every vertex shader must write out a parameter with this semantic. NOTE: This semantic is available in Direct3D 9. For Direct3D 10 and later, use SV_Position instead. | float4 |
| PSIZE | Point size | float |
| TESSFACTOR[n] | Tessellation factor | float |
n is an optional integer between 0 and the number of resources supported. For example, POSITION0, TEXCOORD1, etc.
Pixel Shader Semantics
These semantics have meaning when attached to a pixel-shader input parameter. These semantics are supported in both Direct3D 9 and Direct3D 10 and later.
| Input | Description | Type |
|---|---|---|
| COLOR[n] | Diffuse or specular color. | float4 |
| TEXCOORD[n] | Texture coordinates | float4 |
| VFACE | Floating-point scalar that indicates a back-facing primitive. A negative value faces backwards, while a positive value faces the camera.
Note: |
float |
| VPOS | The pixel location (x,y) in screen space. To convert a Direct3D 9 shader (that uses this semantic) to a Direct3D 10 and later shader, see Direct3D 9 VPOS and Direct3D 10 SV_Position) | float2 |
| Output | Description | Type |
|---|---|---|
| COLOR[n] | Output color | float4 |
| DEPTH[n] | Output depth | float |
n is an optional integer between 0 and the number of resources supported. For example, PSIZE0, COLOR1, etc.
The COLOR semantic is only valid in shader compatibility mode (that is, when the shader is created using D3D10_SHADER_ENABLE_BACKWARDS_COMPATIBILITY).
Semantics Supported Only for Direct3D 10 and Newer.
The following types of semantics have been newly introduced for Direct3D 10 and are not available to Direct3D 9.
System-Value Semantics
System-value semantics are new to Direct3D 10. All system-values begin with an SV_ prefix, a common example is SV_POSITION, which is interpreted by the rasterizer stage. The system-values are valid at other parts of the pipeline. For instance, SV_Position can be specified as an input to a vertex shader as well as an output. Pixel shaders can only write to parameters with the SV_Depth and SV_Target system-value semantics.
Other system values (SV_VertexID, SV_InstanceID, SV_IsFrontFace) can only be input into the first active shader in the pipeline that can interpret the particular value; after that the shader function must pass the values to subsequent stages.
SV_PrimitiveID is an exception to this rule of only being input into the first active shader in the pipeline that can interpret the particular value; the hardware can provide the same ID value as input to the hull-shader stage, domain-shader stage, and after that whichever stage is the first enabled: geometry-shader stage or pixel-shader stage.
If tessellation is enabled, the hull-shader stage and domain-shader stage are present. For a given patch, the same PrimitiveID applies to the patch's hull-shader invocation, and all tessellated domain shader invocations. The same PrimitiveID also propagates to the next active stage; geometry-shader stage or pixel-shader stage if enabled.
If the geometry shader inputs SV_PrimitiveID and because it can output zero or one or more primitives per invocation, the shader must program its own choice of SV_PrimitiveID value for each output primitive if a subsequent pixel shader inputs SV_PrimtiveID.
As another example, SV_PrimitiveID cannot be interpreted by the vertex-shader stage because a vertex can be a member of multiple primitives.
These semantics have been added to Direct3D 10; they are not available in Direct3D 9.
System-value semantics for the rasterizer stage.
| System-Value Semantic | Description | Type |
|---|---|---|
| SV_ClipDistance[n] | Clip distance data. SV_ClipDistance values are each assumed to be a float32 signed distance to a plane. Primitive setup only invokes rasterization on pixels for which the interpolated plane distance(s) are >= 0. Multiple clip planes can be implemented simultaneously, by declaring multiple component(s) of one or more vertex elements as the SV_ClipDistance. The combined clip and cull distance values are at most D3D#_CLIP_OR_CULL_DISTANCE_COUNT components in at most D3D#_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT registers. Available to all shaders to be read or written to, except the vertex shader which can write the value but not take it as input. The clipplanes attribute works like SV_ClipDistance but works on all hardware feature level 9_x and higher. For more info, see User clip planes on feature level 9 hardware. |
float |
| SV_CullDistance[n] | Cull distance data. When component(s) of vertex Element(s) are given this label, these values are each assumed to be a float32 signed distance to a plane. Primitives will be completely discarded if the plane distance(s) for all of the vertices in the primitive are < 0. Multiple cull planes can be used simultaneously, by declaring multiple component(s) of one or more vertex elements as the SV_CullDistance. The combined clip and cull distance values are at most D3D#_CLIP_OR_CULL_DISTANCE_COUNT components in at most D3D#_CLIP_OR_CULL_DISTANCE_ELEMENT_COUNT registers. Available to all shaders to be read or written to, except the vertex shader which can write the value but not take it as input. |
float |
| SV_Coverage | A mask that can be specified on input, output, or both of a pixel shader. For SV_Coverage on a pixel shader, OUTPUT is supported on ps_4_1 or higher. For SV_Coverage on a pixel shader, INPUT requires ps_5_0 or higher. |
uint |
| SV_Depth | Depth buffer data. Can be written by pixel shader. | float |
| SV_DepthGreaterEqual | In a pixel shader, allows outputting depth, as long as it is greater than or equal to the value determined by the rasterizer. Enables adjusting depth without disabling early Z. | float |
| SV_DepthLessEqual | In a pixel shader, allows outputting depth, as long as it is less than or equal to the value determined by the rasterizer. Enables adjusting depth without disabling early Z. | float |
| SV_DispatchThreadID | Defines the global thread offset within the Dispatch call, per dimension of the group. Available as input to compute shader. (read only) | uint3 |
| SV_DomainLocation | Defines the location on the hull of the current domain point being evaluated. Available as input to the domain shader. (read only) | float2|3 |
| SV_GroupID | Defines the group offset within a Dispatch call, per dimension of the dispatch call. Available as input to the compute shader. (read only) | uint3 |
| SV_GroupIndex | Provides a flattened index for a given thread within a given group. Available as input to the compute shader. (read only) | uint |
| SV_GroupThreadID | Defines the thread offset within the group, per dimension of the group. Available as input to the compute shader. (read only) | uint3 |
| SV_GSInstanceID | Defines the instance of the geometry shader. Available as input to the geometry shader. The instance is needed as a geometry shader can be invoked up to 32 times on the same geometry primitive. | uint |
| SV_InnerCoverage | Represents underestimated conservative rasterization information (i.e. whether a pixel is guaranteed-to-be-fully covered). Can be read or written by the pixel shader. | |
| SV_InsideTessFactor | Defines the tessellation amount within a patch surface. Available in the hull shader for writing, and available in the domain shader for reading. | float|float[2] |
| SV_InstanceID | Per-instance identifier automatically generated by the runtime (see Using System-Generated Values (Direct3D 10)). Available to all shaders. | |
| SV_IsFrontFace | Specifies whether a triangle is front facing. For lines and points, IsFrontFace has the value true. The exception is lines drawn out of triangles (wireframe mode), which sets IsFrontFace the same way as rasterizing the triangle in solid mode. Can be written to by the geometry shader, and read by the pixel shader. | bool |
| SV_OutputControlPointID | Defines the index of the control point ID being operated on by an invocation of the main entry point of the hull shader. Can be read by the hull shader only. | uint |
| SV_Position | When SV_Position is declared for input to a shader, it can have one of two interpolation modes specified: linearNoPerspective or linearNoPerspectiveCentroid, where the latter causes centroid-snapped xyzw values to be provided when multisample antialiasing. When used in a shader, SV_Position describes the pixel location. Available in all shaders to get the pixel center with a 0.5 offset. | float4 |
| SV_PrimitiveID | Per-primitive identifier automatically generated by the runtime (see Using System-Generated Values (Direct3D 10)). Can be written to by the geometry or pixel shaders, and read by the geometry, pixel, hull or domain shaders. | uint |
| SV_RenderTargetArrayIndex | Render-target array index. Applied to geometry shader output, and indicates the render target array slice that the primitive will be drawn to by the pixel shader. SV_RenderTargetArrayIndex is valid only if the render target is an array resource. This semantic applies only to primitives; if a primitive has more than one vertex, then the value from the leading vertex is used. This value also indicates which array slice of a depth/stencil view is used for read/write purposes. Can be written from the geometry shader, and read by the pixel shader. If D3D11_FEATURE_DATA_D3D11_OPTIONS3::VPAndRTArrayIndexFromAnyShaderFeedingRasterizer is true, then SV_RenderTargetArrayIndex is applied to any shader feeding the rasterizer. |
uint |
| SV_SampleIndex | Sample frequency index data. Available to be read or written to by the pixel shader only. | uint |
| SV_StencilRef | Represents the current pixel shader stencil reference value. Can be written by the pixel shader only. | uint |
| SV_Target[n], where 0 <= n <= 7 | The output value that will be stored in a render target. The index indicates which of the 8 possibly bound render targets to write to. The value is available to all shaders. | float[2|3|4] |
| SV_TessFactor | Defines the tessellation amount on each edge of a patch. Available for writing in the hull shader and reading in the domain shader. | float[2|3|4] |
| SV_VertexID | Per-vertex identifier automatically generated by the runtime (see Using System-Generated Values (Direct3D 10)). Available as the input to the vertex shader only. | uint |
| SV_ViewportArrayIndex | Viewport array index. Applied to geometry shader output, and indicates which viewport to use for the primitive currently being written out. Can be read by the pixel shader. The primitive will be transformed and clipped against the viewport specified by the index before it is passed to the rasterizer. This semantic applies only to primitives; if a primitive has more than one vertex, then the value from the leading vertex is used. If D3D11_FEATURE_DATA_D3D11_OPTIONS3::VPAndRTArrayIndexFromAnyShaderFeedingRasterizer is true, then SV_ViewportArrayIndex is applied to any shader feeding the rasterizer. |
uint |
| SV_ShadingRate | Defines, through shading rate values, the number of pixels written by one pixel shader invocation for Variable Shading Rate Tier 2 or higher devices. Can be read from the pixel shader. Can be written from a vertex or geometry shader. | uint |
Limitations when writing SV_Depth:
- When multisampling (MultisampleEnable is TRUE in D3D10_RASTERIZER_DESC) and writing a depth value (using a pixel shader), the single value written out is also used in the depth test; so the ability to render primitive edges at higher resolution is lost when multisampling.
- When using dynamic-flow control, it is impossible to determine at compile time whether a shader that writes SV_Depth in some paths will be guaranteed to write SV_Depth in every execution. Failure to write SV_Depth when declared results in undefined behavior (which may or may not include discard of the pixel).
- Any float32 value including +/-INF and NaN can be written to SV_Depth.
- Writing SV_Depth is still valid when performing Dual Source Color Blending.
Migration from Direct3D 9 to Direct3D 10 and later
The following issues should be considered when migrating code from Direct3D 9 to Direct3D 10 and later:
Mapping to Direct3D 9 Semantics
A few of the Direct3D 10 and later semantics map directly to Direct3D 9 semantics.
| Direct3D 10 Semantic | Direct3D 9 Equivalent Semantic |
|---|---|
| SV_Depth | DEPTH |
| SV_Position | POSITION |
| SV_Target | COLOR |
[!] Note to Direct3D 9 developers: For Direct3D 9 targets, shader semantics must map to valid Direct3D 9 semantics. For backwards compatibility, FXC treats POSITION0 (and its variant names) as SV_Position. FXC treats COLOR as SV_TARGET. DXC and newer compilers consider POSITION[n] and COLOR as user-defined semantics.
- Mapping to Direct3D 9 Semantics
- Direct3D 9 VPOS and Direct3D 10 SV_Position
- User clip planes in HLSL
Direct3D 9 VPOS and Direct3D 10 SV_Position
The D3D10 semantic SV_Position provides similar functionality to the Direct3D 9 shader model 3 VPOS semantic. For instance, in Direct3D 9 the following syntax is used for a pixel shader using screen space coordinates:
float4 psMainD3D9( float4 screenSpace : VPOS ) : COLOR
{
// code here
}
VPOS was added for shader model 3 support, to specify screen space coordinates, since the POSITION semantic was intended for object-space coordinates.
In Direct3D 10 and later, the SV_Position semantic (when used in the context of a pixel shader) specifies screen space coordinates (offset by 0.5). Therefore, the Direct3D 9 shader would be roughly equivalent (without accounting for the 0.5 offset) to the following:
float4 psMainD3D10( float4 screenSpace : SV_Position ) : COLOR
{
// code here
}
When migrating from Direct3D 9 to Direct3D 10 and later, you will need to be aware of this when translating your shaders.
User clip planes in HLSL
Starting with Windows 8, you can use the clipplanes function attribute in an HLSL function declaration rather than SV_ClipDistance to make your shader work on feature level 9_x as well as feature level 10 and higher. For more info, see User clip planes on feature level 9 hardware.