SPIR-V specific functionalities

This chapter provides information for SPIR-V specific functionalities and behaviors.

Experimental support for the older versions of SPIR-V

Slang’s SPIRV backend is stable when emitting SPIRV 1.3 and later, however, support for SPIR-V 1.0, 1.1 and 1.2 is still experimental. When targeting the older SPIR-V profiles, Slang may produce SPIR-V that uses the instructions and keywords that were introduced in the later versions of SPIR-V.

Combined texture sampler

Slang supports Combined texture sampler such as Sampler2D. Slang emits SPIR-V code with OpTypeSampledImage instruction.

You can specify two different register numbers for each: one for the texture register and another for the sampler register.

Sampler2D explicitBindingSampler : register(t4): register(s3);

System-Value semantics

The system-value semantics are translated to the following SPIR-V code.

SV semantic name	SPIR-V code
SV_Barycentrics	BuiltIn BaryCoordKHR
SV_ClipDistance<N>	BuiltIn ClipDistance
SV_CullDistance<N>	BuiltIn CullDistance
SV_Coverage	BuiltIn SampleMask
SV_CullPrimitive	BuiltIn CullPrimitiveEXT
SV_Depth	BuiltIn FragDepth
SV_DepthGreaterEqual	BuiltIn FragDepth
SV_DepthLessEqual	BuiltIn FragDepth
SV_DispatchThreadID	BuiltIn GlobalInvocationId
SV_DomainLocation	BuiltIn TessCoord
SV_GSInstanceID	BuiltIn InvocationId
SV_GroupID	BuiltIn WorkgroupId
SV_GroupIndex	BuiltIn LocalInvocationIndex
SV_GroupThreadID	BuiltIn LocalInvocationId
SV_InnerCoverage	BuiltIn FullyCoveredEXT
SV_InsideTessFactor	BuiltIn TessLevelInner
SV_InstanceID	BuiltIn InstanceIndex
SV_IntersectionAttributes	Not supported
SV_IsFrontFace	BuiltIn FrontFacing
SV_OutputControlPointID	BuiltIn InvocationId
SV_PointSize<sup>note</sup>	BuiltIn PointSize
SV_Position	BuiltIn Position/FragCoord
SV_PrimitiveID	BuiltIn PrimitiveId
SV_RenderTargetArrayIndex	BuiltIn Layer
SV_SampleIndex	BuiltIn SampleId
SV_ShadingRate	BuiltIn PrimitiveShadingRateKHR
SV_StartVertexLocation	`Not supported
SV_StartInstanceLocation	`Not suported
SV_StencilRef	BuiltIn FragStencilRefEXT
SV_Target<N>	Location
SV_TessFactor	BuiltIn TessLevelOuter
SV_VertexID	BuiltIn VertexIndex
SV_ViewID	BuiltIn ViewIndex
SV_ViewportArrayIndex	BuiltIn ViewportIndex

Note that SV_PointSize is a unique keyword that HLSL doesn’t have.

Behavior of discard after SPIR-V 1.6

discard is translated to OpKill in SPIR-V 1.5 and earlier. But it is translated to OpDemoteToHelperInvocation in SPIR-V 1.6. You can use OpDemoteToHelperInvocation by explicitly specifying the capability, “SPV_EXT_demote_to_helper_invocation”.

As an example, the following command-line arguments can control the behavior of discard when targeting SPIR-V.

slangc.exe test.slang -target spirv -profile spirv_1_5 # emits OpKill 
slangc.exe test.slang -target spirv -profile spirv_1_6 # emits OpDemoteToHelperInvocation 
slangc.exe test.slang -target spirv -capability SPV_EXT_demote_to_helper_invocation -profile spirv_1_5 # emits OpDemoteToHelperInvocation 

Supported HLSL features when targeting SPIR-V

Slang supports the following HLSL feature sets when targeting SPIR-V.

• ray tracing,
• inline ray tracing,
• mesh shader,
• tessellation shader,
• geometry shader,
• wave intrinsics,
• barriers,
• atomics,
• and more

Unsupported GLSL keywords when targeting SPIR-V

Slang doesn’t support the following Precision qualifiers in Vulkan.

• lowp : RelaxedPrecision, on storage variable and operation
• mediump : RelaxedPrecision, on storage variable and operation
• highp : 32-bit, same as int or float

Slang ignores the keywords above and all of them are treated as highp.

Supported atomic types for each target

Shader Model 6.2 introduced 16-bit scalar types such as float16 and int16_t, but they didn’t come with any atomic operations. Shader Model 6.6 introduced atomic operations for 64-bit integer types and bitwise atomic operations for 32-bit float type, but 16-bit integer types and 16-bit float types are not a part of it.

GLSL 4.3 introduced atomic operations for 32-bit integer types. GLSL 4.4 with GL_EXT_shader_atomic_int64 can use atomic operations for 64-bit integer types. GLSL 4.6 with GLSL_EXT_shader_atomic_float can use atomic operations for 32-bit float type. GLSL 4.6 with GLSL_EXT_shader_atomic_float2 can use atomic operations for 16-bit float type.

SPIR-V 1.5 with SPV_EXT_shader_atomic_float_add and SPV_EXT_shader_atomic_float_min_max can use atomic operations for 32-bit float type and 64-bit float type. SPIR-V 1.5 with SPV_EXT_shader_atomic_float16_add can use atomic operations for 16-bit float type

	32-bit integer	64-bit integer	32-bit float	64-bit float	16-bit float
HLSL	Yes (SM5.0)	Yes (SM6.6)	Only bit-wise (SM6.6)	No	No
GLSL	Yes (GL4.3)	Yes (GL4.4+ext)	Yes (GL4.6+ext)	Yes (GL4.6+ext)	Yes (GL4.6+ext)
SPIR-V	Yes	Yes	Yes (SPV1.5+ext)	Yes (SPV1.5+ext)	Yes (SPV1.5+ext)

ConstantBuffer, (RW/RasterizerOrdered)StructuredBuffer, (RW/RasterizerOrdered)ByteAddressBuffer

Each member in a ConstantBuffer will be emitted as uniform parameter in a uniform block. StructuredBuffer and ByteAddressBuffer are translated to a shader storage buffer with readonly layout. RWStructuredBuffer and RWByteAddressBuffer are translated to a shader storage buffer with read-write layout. RasterizerOrderedStructuredBuffer and RasterizerOrderedByteAddressBuffer will use an extension, SPV_EXT_fragment_shader_interlock.

If you need to apply a different buffer layout for indivisual StructuredBuffer, you can specify the layout as a second generic argument to StructuredBuffer. E.g., StructuredBuffer<T, Std140Layout>, StructuredBuffer<T, Std430Layout> or StructuredBuffer<T, ScalarLayout>.

Note that there are compiler options, “-fvk-use-scalar-layout” and “-force-glsl-scalar-layout”. These options do the same but they are applied globally.

ParameterBlock for SPIR-V target

ParameterBlock is a Slang generic type for binding uniform parameters. It is similar to ConstantBuffer in HLSL, and ParameterBlock can include not only constant parameters but also descriptors such as Texture2D or StructuredBuffer.

ParameterBlock is designed specifically for d3d/vulkan/metal, so that parameters are laid out more naturally on these platforms. For Vulkan, when a ParameterBlock doesn’t contain nested parameter block fields, it always maps to a single descriptor set, with a dedicated set number and every resources is placed into the set with binding index starting from 0.

When both ordinary data fields and resource typed fields exist in a parameter block, all ordinary data fields will be grouped together into a uniform buffer and appear as a binding 0 of the resulting descriptor set.

Push Constants

By default, a uniform parameter defined in the parameter list of an entrypoint function is translated to a push constant in SPIRV, if the type of the parameter is ordinary data type (no resources/textures). All uniform parameter defined in global scope are grouped together and placed in a default constant bbuffer. You can make a global uniform parameter laid out as a push constant by using the [vk::push_constant] attribute on the uniform parameter.

Specialization Constants

You can specify a global constant to translate into a SPIRV specialization constant with the [SpecializationConstant] attribute. For example:

[SpecializationConstant]
const int myConst = 1; // Maps to a SPIRV specialization constant

By default, Slang will automatically assign constant_id number for specialization constants. If you wish to explicitly specify them, use [vk::constant_id] attribute:

[vk::constant_id(1)]
const int myConst = 1;

Alternatively, the GLSL layout syntax is also supported by Slang:

layout(constant_id = 1) const int MyConst = 1;

SPIR-V specific Compiler options

The following compiler options are specific to SPIR-V.

-emit-spirv-directly

Generate SPIR-V output directly (default) It cannot be used with -emit-spirv-via-glsl

-emit-spirv-via-glsl

Generate SPIR-V output by compiling to glsl source first, then use glslang compiler to produce SPIRV from the glsl. It cannot be used with -emit-spirv-directly

-g

Include debug information in the generated code, where possible. When targeting SPIR-V, this option emits SPIR-V NonSemantic Shader DebugInfo Instructions.

-O

Set the optimization level. Under -O0 option, Slang will not perform extensive inlining for all functions calls, instead it will preserve the call graph as much as possible to help with understanding the SPIRV structure and diagnosing any downstream toolchain issues.

-fvk-{b|s|t|u}-shift

For example ‘-fvk-b-shift ' shifts by N the inferred binding numbers for all resources in 'b' registers of space . For a resource attached with :register(bX, ) but not [vk::binding(...)], sets its Vulkan descriptor set to and binding number to X + N. If you need to shift the inferred binding numbers for more than one space, provide more than one such option. If more than one such option is provided for the same space, the last one takes effect. If you need to shift the inferred binding numbers for all sets, use 'all' as .

For more information, see the following pages:

• DXC description
• GLSL wiki

-fvk-bind-globals

Places the $Globals cbuffer at descriptor set and binding . It lets you specify the descriptor for the source at a certain register.

For more information, see the following pages:

• DXC description

-fvk-use-scalar-layout, -force-glsl-scalar-layout

Make data accessed through ConstantBuffer, ParameterBlock, StructuredBuffer, ByteAddressBuffer and general pointers follow the ‘scalar’ layout when targeting GLSL or SPIRV.

-fvk-use-gl-layout

Use std430 layout instead of D3D buffer layout for raw buffer load/stores.

-fvk-use-dx-layout

Pack members using FXCs member packing rules when targeting GLSL or SPIRV.

-fvk-use-entrypoint-name

Uses the entrypoint name from the source instead of ‘main’ in the spirv output.

-fspv-reflect

Include reflection decorations in the resulting SPIRV for shader parameters.

-spirv-core-grammar

A path to a specific spirv.core.grammar.json to use when generating SPIR-V output

SPIR-V specific Attributes

DXC supports a few attributes and command-line arguments for targeting SPIR-V. Similar to DXC, Slang supports a few of the attributes as following:

[[vk::binding(binding: int, set: int = 0)]]

Similar to binding layout qualifier in Vulkan. It specifies the uniform buffer binding point, and the descriptor set for Vulkan.

[[vk::location(X)]]

Same as location layout qualifier in Vulkan. For vertex shader inputs, it specifies the number of the vertex attribute from which input values are taken. For inputs of all other shader types, the location specifies a vector number that can be used to match against outputs from a previous shader stage.

[[vk::index(Y)]]

Same as index layout qualifier in Vulkan. It is valid only when used with [[location(X)]]. For fragment shader outputs, the location and index specify the color output number and index receiving the values of the output. For outputs of all other shader stages, the location specifies a vector number that can be used to match against inputs in a subsequent shader stage.

[[vk::input_attachment_index(i)]]

Same as input_attachment_index layout qualifier in Vulkan. It selects which subpass input is being read from. It is valid only when used on subpassInput type uniform variables.

[[vk::push_constant]]

Same as push_constant layout qualifier in Vulkan. It is applicable only to a uniform block and it will be copied to a special memory location where GPU may have a more direct access to.

[vk::image_format(format : String)]

Same as [[vk::image_format("XX")]] layout qualifier in DXC. Vulkan/GLSL allows the format string to be specified without the keyword, image_format. Consider the following Slang code, as an example,

[vk::image_format("r32f")] RWTexture2D<float> typicalTexture;

It will generate the following GLSL,

layout(r32f) uniform image2D typicalTexture_0;

Or it will generate the following SPIR-V code,

%18 = OpTypeImage %float 2D 2 0 0 2 R32f

[vk::shader_record]

Same as shaderRecordEXT layout qualifier in GL_EXT_ray_tracing extension. It can be used on a buffer block that represents a buffer within a shader record as defined in the Ray Tracing API.

Multiple entry points support

To use multiple entry points, you will need to use a compiler option, -fvk-use-entrypoint-name.

Because GLSL requires the entry point to be named, “main”, a GLSL shader can have only one entry point. The default behavior of Slang is to rename all entry points to “main” when targeting SPIR-V.

When there are more than one entry point, the default behavior will prevent a shader from having more than one entry point. To generate a valid SPIR-V with multiple entry points, use -fvk-use-entrypoint-name compiler option to disable the renaming behavior and preserve the entry point names.

Memory pointer is experimental

Slang supports memory pointers when targetting SPIRV. See an example and explanation.

When a memory pointer points to a physical memory location, the pointer will be translated to a PhysicalStorageBuffer storage class in SPIRV. When a slang module uses a pointer, the resulting SPIRV will be using the SpvAddressingModelPhysicalStorageBuffer64 addressing mode. Modules with pointers but they don’t point to a physical memory location will use SpvAddressingModelLogical addressing mode.

Matrix type translation

A m-row-by-n-column matrix in Slang, represented as floatmxn or matrix<T, m, n>, is translated to OpTypeMatrix (OpTypeVector(T, n), m) in SPIRV. Note that in SPIR-V terminology, this type is referred to a m-column-by-n-row matrix.

The swap of row and column terminology may seem to be confusing at first, but this is the only translation without needing extra operations that may have negative performance consequences. For example, consider the following Slang code:

float3x4 v;
for (int i = 0; i < 3; ++i)
{
  for (int j = 0; j < 4; ++j)
  {
    v[i][j] = i * 4 + j;
  }
}

The Slang shader above can iterate each element of a float3x4 matrix. This is similar to how a multi-dimensional array is handled in C and HLSL. When a matrix type is float3x4, the first dimension indexing, i, corresponds to the first value specified in the matrix type 3. And the second dimension indexing, j, corresponds to the second value specified in the matrix type 4.

A matrix in Slang can be also seen as an array of a vector type. And the following code is same as above.

float3x4 v;
for (int i = 0; i < 3; ++i)
{
  v[i] = float4(0, 1, 2, 3);
  v[i] += i * 4;
}

For the given example above, when targeting SPIR-V, Slang emits a matrix that consists of three vectors each of which has four elements,

%float = OpTypeFloat 32
%v4float = OpTypeVector %float 4 ; <= float4 type
%mat3v4float = OpTypeMatrix %v4float 3 ; <= three of float4

An alternative way to emit SPIR-V code is to emit four vectors and each vector has three elements. Slang doesn’t do this but this is a more direct translation because SPIR-V spec defines OpTypeMatrix to take “Column Count” not row.

; NOT SLANG EMITTED CODE
%v3float = OpTypeVector %float 3 ; <= float3 type
%mat4v3float = OpTypeMatrix %v3float 4 ; <= four of float3

However, this results in a more complicated access pattern to the elements in a matrix, because v[i] will no longer correspond to a vector natively when emitted to SPIR-V.

Another way to put, Slang treats column as row and row as column when targeting GLSL or SPIR-V. This is same to how DXC handles a matrix when emitting SPIR-V.

Due to the swap of row and column in terminology, the matrix multiplication needs to be performed little differently. Slang translates a matrix multiplication, mul(mat1, mat2), to transpose(mul(transpose(mat2), transpose(mat1))) when targeting SPIR-V.

Note that the matrix translation explained above is orthogoal to the memory layout of a matrix. The memory layout is related to how CPU places matrix values in the memory and how GPU reads them. It is like how std140 or std430 works. DXC by default uses column_major memory layout and Slang uses row-major memory layout. For more information about the matrix memory layout, please see a1-01-matrix-layout.

Legalization

Legalization is a process where Slang applies slightly different approach to translate the input Slang shader to the target. This process allows Slang shaders to be written in a syntax that SPIR-V may not be able to achieve natively.

Slang allows to use opaque resource types as members of a struct. These members will be hoisted out of struct types and become global variables.

Slang allows functions that return any resource types as return type or out parameter as long as things are statically resolvable.

Slang allows functions that return arrays. These functions will be converted to return the array via an out parameter in SPIRV.

Slang allows putting scalar/vector/matrix/array types directly as element type of a constant buffer or structured buffers. Such element types will be wrapped in a struct type when emitting to SPIRV.

When RasterizerOrder resources are used, the order of the rasterization is guaranteed by the instructions from SPV_EXT_fragment_shader_interlock extension.

A StructuredBuffer with a primitive type such as StructuredBuffer<int> v is translated to a buffer with a struct that has the primitive type, which is more like struct Temp { int v; }; StructuredBuffer<Temp> v;. It is because, SPIR-V requires buffer variables to be declared within a named buffer block.

When pervertex keyword is used, the given type for the varying input will be translated into an array of the given type whose element size is 3. It is because each triangle consists of three vertices.

Tessellation

In HLSL and Slang, Hull shader requires two functions: a Hull shader and patch function. A typical example of a Hull shader will look like the following.

// Hull Shader (HS)
[domain("quad")]
[patchconstantfunc("constants")]
HS_OUT main(InputPatch<VS_OUT, 4> patch, uint i : SV_OutputControlPointID)
{
  ...
}
HSC_OUT constants(InputPatch<VS_OUT, 4> patch)
{
  ...
}

When targeting SPIR-V, the patch function is merged as a part of the Hull shader, because SPIR-V doesn’t have a same concept as patchconstantfunc. The function used for patchconstantfunc should be called only once for each patch.

As an example, the Hull shader above will be emitted as following,

void main() {
    ...
    main(patch, gl_InvocationID);
    barrier(); // OpControlBarrier
    if (gl_InvocationID == 0)
    {
        constants(path);
    }
}

This behavior is same to how DXC translates Hull shader from HLSL to SPIR-V.