Yotsuba ShaderLearn

SPIR-V syntax

3 min read

Every attribute of the SPIR-V syntax: sPIR-V BuiltIn names (BuiltIn_Position), DescriptorSet and Binding.

The SPIR-V syntax is inspired by SPIR-V (Vulkan). It has 34 attributes in the YotsubaShader.SpirvSyntax package. The syntax you write with does not decide the output: the same shader compiles to any target.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;

public struct VertexOutput
{
    [BuiltIn_Position]
    public Vector4 Position;
}

Built-in values by stage#

Every built-in value the syntax declares, grouped by the stage that uses it.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;

// Vertex stage
public struct VertexBuiltIns
{
    // Clip-space position (vertex output)
    [BuiltIn_Position] public Vector4 ClipSpacePosition;

    // Vertex index
    [BuiltIn_VertexIndex] public int VertexIndex;

    // Instance index
    [BuiltIn_InstanceIndex] public int InstanceIndex;

    // Base vertex
    [BuiltIn_BaseVertex] public int BaseVertex;

    // Base instance
    [BuiltIn_BaseInstance] public int BaseInstance;

    // Clip distance
    [BuiltIn_ClipDistance] public float ClipDistance;

    // Render target layer
    [BuiltIn_Layer] public uint RenderTargetLayer;

    // Viewport index
    [BuiltIn_ViewportIndex] public uint ViewportIndex;
}

// Fragment stage
public struct FragmentBuiltIns
{
    // Fragment coordinate
    [BuiltIn_FragCoord] public Vector4 FragmentCoordinate;

    // Front-facing flag
    [BuiltIn_FrontFacing] public bool FrontFacingFlag;

    // Fragment depth (output)
    [BuiltIn_FragDepth] public float FragmentDepth;

    // Stencil reference (output)
    [BuiltIn_FragStencilRef] public uint StencilReference;

    // Sample index
    [BuiltIn_SampleId] public uint SampleIndex;

    // Sample mask
    [BuiltIn_SampleMask] public uint SampleMask;

    // Primitive index
    [BuiltIn_PrimitiveId] public uint PrimitiveIndex;

    // Barycentric coordinates
    [BuiltIn_BaryCoord] public Vector4 BarycentricCoordinates;

    // Barycentric coordinates (no perspective)
    [BuiltIn_BaryCoordNoPersp] public Vector4 BarycentricCoordinates2;

    // Helper invocation
    [BuiltIn_HelperInvocation] public bool HelperInvocation;

    // Sample position
    [BuiltIn_SamplePosition] public Vector2 SamplePosition;
}

// Compute stage
public class ComputeBuiltIns
{
    // Global invocation id
    [BuiltIn_GlobalInvocationId] public UInt3 GlobalInvocationId;

    // Local invocation id
    [BuiltIn_LocalInvocationId] public UInt3 LocalInvocationId;

    // Local invocation index
    [BuiltIn_LocalInvocationIndex] public uint LocalInvocationIndex;

    // Workgroup id
    [BuiltIn_WorkgroupId] public UInt3 WorkgroupId;

    // Number of workgroups
    [BuiltIn_NumWorkgroups] public UInt3 NumberOfWorkgroups;

    // Workgroup size (built-in value)
    [BuiltIn_WorkgroupSize] public UInt3 WorkgroupSize;

    // Subgroup size
    [BuiltIn_SubgroupSize] public uint SubgroupSize;

    // Subgroup invocation id
    [BuiltIn_SubgroupInvocationId] public UInt3 SubgroupInvocationId;

    // Subgroup id
    [BuiltIn_SubgroupId] public uint SubgroupId;

    // Number of subgroups
    [BuiltIn_NumSubgroups] public uint NumberOfSubgroups;
}

Resources and binding slots#

Uniform buffers, storage buffers, textures and samplers, each with its slot written in this syntax.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;
using YotsubaShader.SpirvSyntax.Resources;

public struct Material
{
    public float Exposure;
}

public class Resources
{
    // Uniform buffer, with its binding slot
    [Uniform, DescriptorSet(0), @Binding(0)]
    public Material Material;

    // Read/write storage buffer
    [StorageBuffer, DescriptorSet(0), @Binding(1)]
    public float[] Output;

    // Read-only storage buffer (same attribute)
    [StorageBuffer, DescriptorSet(0), @Binding(2)]
    public float[] Input;
}
using YotsubaShader.SpirvSyntax;
using YotsubaShader.SpirvSyntax.Resources;

public class Surface
{
    [DescriptorSet(0), @Binding(0)]
    public Texture2D Albedo;

    [DescriptorSet(0), @Binding(1)]
    public SamplerState Sampler;
}

Equivalents in the other syntaxes#

The same concept in SPIR-V and in the other four syntaxes. A dash means that the syntax has no spelling for it.

Built-in values#

ConceptSPIR-VHLSLGLSLMSLWGSL
Vertex stage
Clip-space position (vertex output)BuiltIn_PositionSV_Positiongl_Positionposition@builtin_position
Vertex indexBuiltIn_VertexIndexSV_VertexIDgl_VertexIndexvertex_id@builtin_vertex_index
Instance indexBuiltIn_InstanceIndexSV_InstanceIDgl_InstanceIndexinstance_id@builtin_instance_index
Base vertexBuiltIn_BaseVertexSV_StartVertexLocationgl_BaseVertexbase_vertex—
Base instanceBuiltIn_BaseInstanceSV_StartInstanceLocationgl_BaseInstancebase_instance—
Clip distanceBuiltIn_ClipDistanceSV_ClipDistanceNgl_ClipDistanceclip_distance@builtin_clip_distances
Render target layerBuiltIn_LayerSV_RenderTargetArrayIndexgl_Layerrender_target_array_index—
Viewport indexBuiltIn_ViewportIndexSV_ViewportArrayIndexgl_ViewportIndexviewport_array_index—
Fragment stage
Fragment coordinateBuiltIn_FragCoordSV_Positiongl_FragCoordposition@builtin_position
Front-facing flagBuiltIn_FrontFacingSV_IsFrontFacegl_FrontFacingfront_facing@builtin_front_facing
Fragment depth (output)BuiltIn_FragDepthSV_Depthgl_FragDepthdepth@builtin_frag_depth
Conservative depth—SV_DepthGreaterEqual / SV_DepthLessEqual—depth("greater") / depth("less")—
Stencil reference (output)BuiltIn_FragStencilRefSV_StencilRefgl_FragStencilRefARBstencil—
Sample indexBuiltIn_SampleIdSV_SampleIndexgl_SampleIDsample_id@builtin_sample_index
Sample maskBuiltIn_SampleMaskSV_Coveragegl_SampleMask / gl_SampleMaskInsample_mask@builtin_sample_mask
Primitive indexBuiltIn_PrimitiveIdSV_PrimitiveIDgl_PrimitiveIDprimitive_id@builtin_primitive_index
Barycentric coordinatesBuiltIn_BaryCoordSV_Barycentricsgl_BaryCoordEXTbarycentric_coord—
Barycentric coordinates (no perspective)BuiltIn_BaryCoordNoPersp—gl_BaryCoordNoPerspEXT——
Helper invocationBuiltIn_HelperInvocation—gl_HelperInvocation——
Sample positionBuiltIn_SamplePosition—gl_SamplePosition——
Compute stage
Global invocation idBuiltIn_GlobalInvocationIdSV_DispatchThreadIDgl_GlobalInvocationIDthread_position_in_grid@builtin_global_invocation_id
Local invocation idBuiltIn_LocalInvocationIdSV_GroupThreadIDgl_LocalInvocationIDthread_position_in_threadgroup@builtin_local_invocation_id
Local invocation indexBuiltIn_LocalInvocationIndexSV_GroupIndexgl_LocalInvocationIndexthread_index_in_threadgroup@builtin_local_invocation_index
Workgroup idBuiltIn_WorkgroupIdSV_GroupIDgl_WorkGroupIDthreadgroup_position_in_grid@builtin_workgroup_id
Number of workgroupsBuiltIn_NumWorkgroups—gl_NumWorkGroupsthreadgroups_per_grid@builtin_num_workgroups
Workgroup size (method attribute)—numthreadslayout_local_size—@workgroup_size
Workgroup size (built-in value)BuiltIn_WorkgroupSize—gl_WorkGroupSizethreads_per_threadgroup—
Subgroup sizeBuiltIn_SubgroupSize—gl_SubgroupSizethreads_per_simdgroup@builtin_subgroup_size
Subgroup invocation idBuiltIn_SubgroupInvocationId—gl_SubgroupInvocationIDthread_index_in_simdgroup@builtin_subgroup_invocation_id
Subgroup idBuiltIn_SubgroupId—gl_SubgroupIDsimdgroup_index_in_threadgroup@builtin_subgroup_id
Number of subgroupsBuiltIn_NumSubgroups—gl_NumSubgroupssimdgroups_per_threadgroup@builtin_num_subgroups

Resources#

ConceptSPIR-VHLSLGLSLMSLWGSL
Uniform bufferUniformcbuffer, ConstantBuffer<T>uniformconstantuniform
Read/write storage bufferStorageBufferRWStructuredBuffer<T>bufferdevicestorage(storage_use.read_write)
Read-only storage bufferStorageBufferStructuredBuffer<T>bufferdevice(readOnly: true)storage(storage_use.read)
Binding slotDescriptorSet(s) + Binding(n)register(RegisterPrefix.b, n)layout(set, binding)buffer(n), texture(n), sampler(n)@group(s) + @binding(n)
Texture slotDescriptorSet(s) + Binding(n)register(RegisterPrefix.t, n)layout(set, binding)texture(n)@group(s) + @binding(n)
Sampler slotDescriptorSet(s) + Binding(n)register(RegisterPrefix.s, n)layout(set, binding)sampler(n)@group(s) + @binding(n)

Attributes#

The attributes declared by the package, in groups, applied to real members.

Input attributes#

Apply to fields, parameters and properties that receive values from the pipeline.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;

public struct InputExamples
{
    // Barycentric coordinates
    [BuiltIn_BaryCoord] public Vector4 BarycentricCoordinates;
    // Barycentric coordinates (no perspective)
    [BuiltIn_BaryCoordNoPersp]
    public Vector4 BarycentricCoordinates2;
    // Base instance
    [BuiltIn_BaseInstance] public int BaseInstance;
    // Base vertex
    [BuiltIn_BaseVertex] public int BaseVertex;
    // Fragment coordinate
    [BuiltIn_FragCoord] public Vector4 FragmentCoordinate;
    // Front-facing flag
    [BuiltIn_FrontFacing] public bool FrontFacingFlag;
    // Global invocation id
    [BuiltIn_GlobalInvocationId]
    public UInt3 GlobalInvocationId;
    // Helper invocation
    [BuiltIn_HelperInvocation] public bool HelperInvocation;
    // Instance index
    [BuiltIn_InstanceIndex] public int InstanceIndex;
    // Local invocation id
    [BuiltIn_LocalInvocationId] public UInt3 LocalInvocationId;
    // Local invocation index
    [BuiltIn_LocalInvocationIndex]
    public uint LocalInvocationIndex;
    // Number of subgroups
    [BuiltIn_NumSubgroups] public uint NumberOfSubgroups;
    // Number of workgroups
    [BuiltIn_NumWorkgroups] public UInt3 NumberOfWorkgroups;
    // Primitive index
    [BuiltIn_PrimitiveId] public uint PrimitiveIndex;
    // Sample index
    [BuiltIn_SampleId] public uint SampleIndex;
    // Sample position
    [BuiltIn_SamplePosition] public Vector2 SamplePosition;
    // Subgroup id
    [BuiltIn_SubgroupId] public uint SubgroupId;
    // Subgroup invocation id
    [BuiltIn_SubgroupInvocationId]
    public UInt3 SubgroupInvocationId;
    // Subgroup size
    [BuiltIn_SubgroupSize] public uint SubgroupSize;
    // Vertex index
    [BuiltIn_VertexIndex] public int VertexIndex;
    // Workgroup id
    [BuiltIn_WorkgroupId] public UInt3 WorkgroupId;
    // Workgroup size (built-in value)
    [BuiltIn_WorkgroupSize] public UInt3 WorkgroupSize;
}

Input and output attributes#

Apply to values that can be received or produced, depending on the stage.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;

public struct InputOutputExamples
{
    // Clip distance
    [BuiltIn_ClipDistance] public float ClipDistance;
    // Render target layer
    [BuiltIn_Layer] public uint RenderTargetLayer;
    // Clip-space position (vertex output)
    [BuiltIn_Position] public Vector4 ClipSpacePosition;
    // Sample mask
    [BuiltIn_SampleMask] public uint SampleMask;
    // Viewport index
    [BuiltIn_ViewportIndex] public uint ViewportIndex;
    [Location] public Vector4 Value6;
}

Output attributes#

Apply to fields, parameters and return values the stage produces.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;

public struct OutputExamples
{
    // Fragment depth (output)
    [BuiltIn_FragDepth] public float FragmentDepth;
    // Stencil reference (output)
    [BuiltIn_FragStencilRef] public uint StencilReference;
}

Resource attributes#

Declare uniforms, buffers, textures, samplers and binding slots.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;
using YotsubaShader.SpirvSyntax.Resources;

public class ResourceExamples
{
    [@Binding(0)] public float Value1;
    [DescriptorSet(0)] public float Value2;
    [StorageBuffer] public float Value3;
    [Uniform] public float Value4;
}

Supporting types#

Structs, classes and enums used together with the attributes.

using YotsubaShader.Language;
using YotsubaShader.SpirvSyntax;

public class Types
{
    public YotsubaShader.SpirvSyntax.Types.bvec2 Bvec2Value;
    public YotsubaShader.SpirvSyntax.Types.bvec3 Bvec3Value;
    public YotsubaShader.SpirvSyntax.Types.bvec4 Bvec4Value;
    public YotsubaShader.SpirvSyntax.Types.dmat2 Dmat2Value;
    public YotsubaShader.SpirvSyntax.Types.dmat2x2 Dmat2x2Value;
    public YotsubaShader.SpirvSyntax.Types.dmat2x3 Dmat2x3Value;
    public YotsubaShader.SpirvSyntax.Types.dmat2x4 Dmat2x4Value;
    public YotsubaShader.SpirvSyntax.Types.dmat3 Dmat3Value;
    public YotsubaShader.SpirvSyntax.Types.dmat3x2 Dmat3x2Value;
    public YotsubaShader.SpirvSyntax.Types.dmat3x3 Dmat3x3Value;
    public YotsubaShader.SpirvSyntax.Types.dmat3x4 Dmat3x4Value;
    public YotsubaShader.SpirvSyntax.Types.dmat4 Dmat4Value;
    public YotsubaShader.SpirvSyntax.Types.dmat4x2 Dmat4x2Value;
    public YotsubaShader.SpirvSyntax.Types.dmat4x3 Dmat4x3Value;
    public YotsubaShader.SpirvSyntax.Types.dmat4x4 Dmat4x4Value;
    public YotsubaShader.SpirvSyntax.Types.dvec2 Dvec2Value;
    public YotsubaShader.SpirvSyntax.Types.dvec3 Dvec3Value;
    public YotsubaShader.SpirvSyntax.Types.dvec4 Dvec4Value;
    public YotsubaShader.SpirvSyntax.Resources.Types.iimage1D Iimage1DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.iimage2D Iimage2DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.iimage2DArray Iimage2DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.iimage2DMS Iimage2DMSValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.iimage3D Iimage3DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.iimageCube IimageCubeValue;
    public YotsubaShader.SpirvSyntax.Resources.Type.Image1D<float> Image1DGenericValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.image1D Image1DValue;
    public YotsubaShader.SpirvSyntax.Resources.Type.Image2D<float> Image2DGenericValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.image2D Image2DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.image2DArray Image2DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.image2DMS Image2DMSValue;
    public YotsubaShader.SpirvSyntax.Resources.Type.Image3D<float> Image3DGenericValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.image3D Image3DValue;
    public YotsubaShader.SpirvSyntax.Resources.Type.ImageCube<float> ImageCubeGenericValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.imageCube ImageCubeValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler1D Isampler1DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler1DArray Isampler1DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler2D Isampler2DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler2DArray Isampler2DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler2DMS Isampler2DMSValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler2DMSArray Isampler2DMSArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isampler3D Isampler3DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isamplerBuffer IsamplerBufferValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isamplerCube IsamplerCubeValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.isamplerCubeArray IsamplerCubeArrayValue;
    public YotsubaShader.SpirvSyntax.Types.ivec2 Ivec2Value;
    public YotsubaShader.SpirvSyntax.Types.ivec3 Ivec3Value;
    public YotsubaShader.SpirvSyntax.Types.ivec4 Ivec4Value;
    public YotsubaShader.SpirvSyntax.Types.mat2 Mat2Value;
    public YotsubaShader.SpirvSyntax.Types.mat2x2 Mat2x2Value;
    public YotsubaShader.SpirvSyntax.Types.mat2x3 Mat2x3Value;
    public YotsubaShader.SpirvSyntax.Types.mat2x4 Mat2x4Value;
    public YotsubaShader.SpirvSyntax.Types.mat3 Mat3Value;
    public YotsubaShader.SpirvSyntax.Types.mat3x2 Mat3x2Value;
    public YotsubaShader.SpirvSyntax.Types.mat3x3 Mat3x3Value;
    public YotsubaShader.SpirvSyntax.Types.mat3x4 Mat3x4Value;
    public YotsubaShader.SpirvSyntax.Types.mat4 Mat4Value;
    public YotsubaShader.SpirvSyntax.Types.mat4x2 Mat4x2Value;
    public YotsubaShader.SpirvSyntax.Types.mat4x3 Mat4x3Value;
    public YotsubaShader.SpirvSyntax.Types.mat4x4 Mat4x4Value;
    public YotsubaShader.SpirvSyntax.Resources.Type.Sampler SamplerValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler1D Sampler1DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler1DArray Sampler1DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler1DArrayShadow Sampler1DArrayShadowValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler1DShadow Sampler1DShadowValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler2D Sampler2DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler2DArray Sampler2DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler2DArrayShadow Sampler2DArrayShadowValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler2DMS Sampler2DMSValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler2DMSArray Sampler2DMSArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler2DShadow Sampler2DShadowValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.sampler3D Sampler3DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.samplerBuffer SamplerBufferValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.samplerCube SamplerCubeValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.samplerCubeArray SamplerCubeArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.samplerCubeArrayShadow SamplerCubeArrayShadowValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.samplerCubeShadow SamplerCubeShadowValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.uimage1D Uimage1DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.uimage2D Uimage2DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.uimage2DArray Uimage2DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.uimage2DMS Uimage2DMSValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.uimage3D Uimage3DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.uimageCube UimageCubeValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler1D Usampler1DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler1DArray Usampler1DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler2D Usampler2DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler2DArray Usampler2DArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler2DMS Usampler2DMSValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler2DMSArray Usampler2DMSArrayValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usampler3D Usampler3DValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usamplerBuffer UsamplerBufferValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usamplerCube UsamplerCubeValue;
    public YotsubaShader.SpirvSyntax.Resources.Types.usamplerCubeArray UsamplerCubeArrayValue;
    public YotsubaShader.SpirvSyntax.Types.uvec2 Uvec2Value;
    public YotsubaShader.SpirvSyntax.Types.uvec3 Uvec3Value;
    public YotsubaShader.SpirvSyntax.Types.uvec4 Uvec4Value;
    public YotsubaShader.SpirvSyntax.Types.vec2 Vec2Value;
    public YotsubaShader.SpirvSyntax.Types.vec3 Vec3Value;
    public YotsubaShader.SpirvSyntax.Types.vec4 Vec4Value;
}

The other syntaxes: HLSL, GLSL, MSL, WGSL.