Yotsuba ShaderLearn

HLSL syntax

3 min read

Every attribute of the HLSL syntax: system-value semantics such as SV_Position and numthreads, plus cbuffer and register for resources.

The HLSL syntax is inspired by HLSL (Direct3D). It has 31 attributes in the YotsubaShader.HlslSyntax package. The syntax you write with does not decide the output: the same shader compiles to any target.

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

public struct VertexOutput
{
    [SV_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.HlslSyntax;

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

    // Vertex index
    [SV_VertexID] public uint VertexIndex;

    // Instance index
    [SV_InstanceID] public uint InstanceIndex;

    // Base vertex
    [SV_StartVertexLocation] public uint BaseVertex;

    // Base instance
    [SV_StartInstanceLocation] public uint BaseInstance;

    // Clip distance
    [SV_ClipDistanceN] public float ClipDistance;

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

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

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

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

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

    // Conservative depth
    [SV_DepthGreaterEqual] public float ConservativeDepth;

    // Conservative depth
    [SV_DepthLessEqual] public float ConservativeDepth2;

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

    // Sample index
    [SV_SampleIndex] public uint SampleIndex;

    // Sample mask
    [SV_Coverage] public uint SampleMask;

    // Primitive index
    [SV_PrimitiveID] public uint PrimitiveIndex;

    // Barycentric coordinates
    [SV_Barycentrics] public Vector4 BarycentricCoordinates;
}

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

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

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

    // Workgroup id
    [SV_GroupID] public UInt3 WorkgroupId;

    // Workgroup size (method attribute)
    [ShaderStage(Stage.Compute)]
    [numthreads(8, 8, 1)]
    public void Compute() { }
}

Resources and binding slots#

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

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;
using YotsubaShader.HlslSyntax.Resources;

public struct Material
{
    public float Exposure;
}

public class Resources
{
    // Uniform buffer, with its binding slot
    [cbuffer, register(RegisterPrefix.b, 0)]
    public Material Material;

    // Read/write storage buffer
    [register(RegisterPrefix.u, 0)]
    public RWStructuredBuffer<float> Output;

    // Read-only storage buffer
    [register("t0")]
    public StructuredBuffer<float> Input;
}
using YotsubaShader.HlslSyntax;
using YotsubaShader.HlslSyntax.Resources;

public class Surface
{
    [register(RegisterPrefix.t, 0)]
    public Texture2D Albedo;

    // The same register, written as a string: letter + number
    [register("s0")]
    public SamplerState Sampler;
}

Equivalents in the other syntaxes#

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

Built-in values#

ConceptHLSLGLSLMSLSPIR-VWGSL
Vertex stage
Clip-space position (vertex output)SV_Positiongl_PositionpositionBuiltIn_Position@builtin_position
Vertex indexSV_VertexIDgl_VertexIndexvertex_idBuiltIn_VertexIndex@builtin_vertex_index
Instance indexSV_InstanceIDgl_InstanceIndexinstance_idBuiltIn_InstanceIndex@builtin_instance_index
Base vertexSV_StartVertexLocationgl_BaseVertexbase_vertexBuiltIn_BaseVertex—
Base instanceSV_StartInstanceLocationgl_BaseInstancebase_instanceBuiltIn_BaseInstance—
Clip distanceSV_ClipDistanceNgl_ClipDistanceclip_distanceBuiltIn_ClipDistance@builtin_clip_distances
Render target layerSV_RenderTargetArrayIndexgl_Layerrender_target_array_indexBuiltIn_Layer—
Viewport indexSV_ViewportArrayIndexgl_ViewportIndexviewport_array_indexBuiltIn_ViewportIndex—
Fragment stage
Fragment coordinateSV_Positiongl_FragCoordpositionBuiltIn_FragCoord@builtin_position
Front-facing flagSV_IsFrontFacegl_FrontFacingfront_facingBuiltIn_FrontFacing@builtin_front_facing
Fragment depth (output)SV_Depthgl_FragDepthdepthBuiltIn_FragDepth@builtin_frag_depth
Conservative depthSV_DepthGreaterEqual / SV_DepthLessEqual—depth("greater") / depth("less")——
Stencil reference (output)SV_StencilRefgl_FragStencilRefARBstencilBuiltIn_FragStencilRef—
Sample indexSV_SampleIndexgl_SampleIDsample_idBuiltIn_SampleId@builtin_sample_index
Sample maskSV_Coveragegl_SampleMask / gl_SampleMaskInsample_maskBuiltIn_SampleMask@builtin_sample_mask
Primitive indexSV_PrimitiveIDgl_PrimitiveIDprimitive_idBuiltIn_PrimitiveId@builtin_primitive_index
Barycentric coordinatesSV_Barycentricsgl_BaryCoordEXTbarycentric_coordBuiltIn_BaryCoord—
Barycentric coordinates (no perspective)—gl_BaryCoordNoPerspEXT—BuiltIn_BaryCoordNoPersp—
Helper invocation—gl_HelperInvocation—BuiltIn_HelperInvocation—
Sample position—gl_SamplePosition—BuiltIn_SamplePosition—
Compute stage
Global invocation idSV_DispatchThreadIDgl_GlobalInvocationIDthread_position_in_gridBuiltIn_GlobalInvocationId@builtin_global_invocation_id
Local invocation idSV_GroupThreadIDgl_LocalInvocationIDthread_position_in_threadgroupBuiltIn_LocalInvocationId@builtin_local_invocation_id
Local invocation indexSV_GroupIndexgl_LocalInvocationIndexthread_index_in_threadgroupBuiltIn_LocalInvocationIndex@builtin_local_invocation_index
Workgroup idSV_GroupIDgl_WorkGroupIDthreadgroup_position_in_gridBuiltIn_WorkgroupId@builtin_workgroup_id
Number of workgroups—gl_NumWorkGroupsthreadgroups_per_gridBuiltIn_NumWorkgroups@builtin_num_workgroups
Workgroup size (method attribute)numthreadslayout_local_size——@workgroup_size
Workgroup size (built-in value)—gl_WorkGroupSizethreads_per_threadgroupBuiltIn_WorkgroupSize—
Subgroup size—gl_SubgroupSizethreads_per_simdgroupBuiltIn_SubgroupSize@builtin_subgroup_size
Subgroup invocation id—gl_SubgroupInvocationIDthread_index_in_simdgroupBuiltIn_SubgroupInvocationId@builtin_subgroup_invocation_id
Subgroup id—gl_SubgroupIDsimdgroup_index_in_threadgroupBuiltIn_SubgroupId@builtin_subgroup_id
Number of subgroups—gl_NumSubgroupssimdgroups_per_threadgroupBuiltIn_NumSubgroups@builtin_num_subgroups

Resources#

ConceptHLSLGLSLMSLSPIR-VWGSL
Uniform buffercbuffer, ConstantBuffer<T>uniformconstantUniformuniform
Read/write storage bufferRWStructuredBuffer<T>bufferdeviceStorageBufferstorage(storage_use.read_write)
Read-only storage bufferStructuredBuffer<T>bufferdevice(readOnly: true)StorageBufferstorage(storage_use.read)
Binding slotregister(RegisterPrefix.b, n)layout(set, binding)buffer(n), texture(n), sampler(n)DescriptorSet(s) + Binding(n)@group(s) + @binding(n)
Texture slotregister(RegisterPrefix.t, n)layout(set, binding)texture(n)DescriptorSet(s) + Binding(n)@group(s) + @binding(n)
Sampler slotregister(RegisterPrefix.s, n)layout(set, binding)sampler(n)DescriptorSet(s) + Binding(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.HlslSyntax;

public struct InputExamples
{
    // Barycentric coordinates
    [SV_Barycentrics] public Vector4 BarycentricCoordinates;
    // Global invocation id
    [SV_DispatchThreadID] public UInt3 GlobalInvocationId;
    // Workgroup id
    [SV_GroupID] public UInt3 WorkgroupId;
    // Local invocation index
    [SV_GroupIndex] public uint LocalInvocationIndex;
    // Local invocation id
    [SV_GroupThreadID] public UInt3 LocalInvocationId;
    // Instance index
    [SV_InstanceID] public uint InstanceIndex;
    // Front-facing flag
    [SV_IsFrontFace] public bool FrontFacingFlag;
    // Primitive index
    [SV_PrimitiveID] public uint PrimitiveIndex;
    // Sample index
    [SV_SampleIndex] public uint SampleIndex;
    // Base instance
    [SV_StartInstanceLocation] public uint BaseInstance;
    // Base vertex
    [SV_StartVertexLocation] public uint BaseVertex;
    // Vertex index
    [SV_VertexID] public uint VertexIndex;
}

Input and output attributes#

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

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

public struct InputOutputExamples
{
    [BINORMAL] public Vector4 Value1;
    [COLOR] public Vector4 Value2;
    [NORMAL] public Vector4 Value3;
    [POSITION] public Vector4 Value4;
    [SV_ClipDistanceN] public Vector4 Value5;
    // Sample mask
    [SV_Coverage] public uint SampleMask;
    // Clip-space position (vertex output)
    [SV_Position] public Vector4 ClipSpacePosition;
    // Render target layer
    [SV_RenderTargetArrayIndex] public uint RenderTargetLayer;
    // Viewport index
    [SV_ViewportArrayIndex] public uint ViewportIndex;
    [TANGENT] public Vector4 Value10;
    [TEXCOORD] public Vector4 Value11;
}

Output attributes#

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

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

public struct OutputExamples
{
    // Fragment depth (output)
    [SV_Depth] public float FragmentDepth;
    // Conservative depth
    [SV_DepthGreaterEqual] public float ConservativeDepth;
    // Conservative depth
    [SV_DepthLessEqual] public float ConservativeDepth2;
    // Stencil reference (output)
    [SV_StencilRef] public uint StencilReference;
    [SV_Target] public Vector4 Value5;
}

Method attributes#

Apply to methods, for example to set a compute workgroup size.

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

public class MethodExamples
{
    [ShaderStage(Stage.Compute)]
    [numthreads(8, 8, 1)]
    public void NumthreadsExample() { }
}

Resource attributes#

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

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;
using YotsubaShader.HlslSyntax.Resources;

public class ResourceExamples
{
    [cbuffer] public float Value1;
    [register(RegisterPrefix.b, 0)] public float Value2;

    // The string overload: letter + number
    [register("b1")]
    public float Value3;
}

Supporting types#

Structs, classes and enums used together with the attributes.

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

public class Types
{
    public YotsubaShader.HlslSyntax.Types.bool2 Bool2Value;
    public YotsubaShader.HlslSyntax.Types.bool2x2 Bool2x2Value;
    public YotsubaShader.HlslSyntax.Types.bool2x3 Bool2x3Value;
    public YotsubaShader.HlslSyntax.Types.bool2x4 Bool2x4Value;
    public YotsubaShader.HlslSyntax.Types.bool3 Bool3Value;
    public YotsubaShader.HlslSyntax.Types.bool3x2 Bool3x2Value;
    public YotsubaShader.HlslSyntax.Types.bool3x3 Bool3x3Value;
    public YotsubaShader.HlslSyntax.Types.bool3x4 Bool3x4Value;
    public YotsubaShader.HlslSyntax.Types.bool4 Bool4Value;
    public YotsubaShader.HlslSyntax.Types.bool4x2 Bool4x2Value;
    public YotsubaShader.HlslSyntax.Types.bool4x3 Bool4x3Value;
    public YotsubaShader.HlslSyntax.Types.bool4x4 Bool4x4Value;
    public YotsubaShader.HlslSyntax.Resources.ConstantBuffer<float> ConstantBufferGenericValue;
    public YotsubaShader.HlslSyntax.Types.float2 Float2Value;
    public YotsubaShader.HlslSyntax.Types.float2x2 Float2x2Value;
    public YotsubaShader.HlslSyntax.Types.float2x3 Float2x3Value;
    public YotsubaShader.HlslSyntax.Types.float2x4 Float2x4Value;
    public YotsubaShader.HlslSyntax.Types.float3 Float3Value;
    public YotsubaShader.HlslSyntax.Types.float3x2 Float3x2Value;
    public YotsubaShader.HlslSyntax.Types.float3x3 Float3x3Value;
    public YotsubaShader.HlslSyntax.Types.float3x4 Float3x4Value;
    public YotsubaShader.HlslSyntax.Types.float4 Float4Value;
    public YotsubaShader.HlslSyntax.Types.float4x2 Float4x2Value;
    public YotsubaShader.HlslSyntax.Types.float4x3 Float4x3Value;
    public YotsubaShader.HlslSyntax.Types.float4x4 Float4x4Value;
    public YotsubaShader.HlslSyntax.Types.int2 Int2Value;
    public YotsubaShader.HlslSyntax.Types.int2x2 Int2x2Value;
    public YotsubaShader.HlslSyntax.Types.int2x3 Int2x3Value;
    public YotsubaShader.HlslSyntax.Types.int2x4 Int2x4Value;
    public YotsubaShader.HlslSyntax.Types.int3 Int3Value;
    public YotsubaShader.HlslSyntax.Types.int3x2 Int3x2Value;
    public YotsubaShader.HlslSyntax.Types.int3x3 Int3x3Value;
    public YotsubaShader.HlslSyntax.Types.int3x4 Int3x4Value;
    public YotsubaShader.HlslSyntax.Types.int4 Int4Value;
    public YotsubaShader.HlslSyntax.Types.int4x2 Int4x2Value;
    public YotsubaShader.HlslSyntax.Types.int4x3 Int4x3Value;
    public YotsubaShader.HlslSyntax.Types.int4x4 Int4x4Value;
    public YotsubaShader.HlslSyntax.Resources.RegisterPrefix RegisterPrefixValue;
    public YotsubaShader.HlslSyntax.Resources.RWStructuredBuffer<float> RWStructuredBufferGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.RWTexture2D<float> RWTexture2DGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.SamplerComparisonState SamplerComparisonStateValue;
    public YotsubaShader.HlslSyntax.Resources.Types.SamplerState SamplerStateValue;
    public YotsubaShader.HlslSyntax.Resources.StructuredBuffer<float> StructuredBufferGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture1D Texture1DValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture1D<float> Texture1DGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2D Texture2DValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2D<float> Texture2DGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2DArray Texture2DArrayValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2DArray<float> Texture2DArrayGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2DMS<float> Texture2DMSGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2DMS Texture2DMSValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2DMSArray Texture2DMSArrayValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture2DMSArray<float> Texture2DMSArrayGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture3D Texture3DValue;
    public YotsubaShader.HlslSyntax.Resources.Types.Texture3D<float> Texture3DGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.TextureCube TextureCubeValue;
    public YotsubaShader.HlslSyntax.Resources.Types.TextureCube<float> TextureCubeGenericValue;
    public YotsubaShader.HlslSyntax.Resources.Types.TextureCubeArray TextureCubeArrayValue;
    public YotsubaShader.HlslSyntax.Resources.Types.TextureCubeArray<float> TextureCubeArrayGenericValue;
    public YotsubaShader.HlslSyntax.Types.uint2 Uint2Value;
    public YotsubaShader.HlslSyntax.Types.uint2x2 Uint2x2Value;
    public YotsubaShader.HlslSyntax.Types.uint2x3 Uint2x3Value;
    public YotsubaShader.HlslSyntax.Types.uint2x4 Uint2x4Value;
    public YotsubaShader.HlslSyntax.Types.uint3 Uint3Value;
    public YotsubaShader.HlslSyntax.Types.uint3x2 Uint3x2Value;
    public YotsubaShader.HlslSyntax.Types.uint3x3 Uint3x3Value;
    public YotsubaShader.HlslSyntax.Types.uint3x4 Uint3x4Value;
    public YotsubaShader.HlslSyntax.Types.uint4 Uint4Value;
    public YotsubaShader.HlslSyntax.Types.uint4x2 Uint4x2Value;
    public YotsubaShader.HlslSyntax.Types.uint4x3 Uint4x3Value;
    public YotsubaShader.HlslSyntax.Types.uint4x4 Uint4x4Value;
}

The other syntaxes: GLSL, MSL, SPIR-V, WGSL.