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:
This semantic is available in Direct3D 9 Shader Model 3.0. For Direct3D 10 and later, use SV_IsFrontFace instead.


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.

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.