Yotsuba ShaderLearn

WGSL syntax

3 min read

Every attribute of the WGSL syntax: the @builtin(...), @group and @binding vocabulary of WebGPU, written with @ identifiers that remain valid C#.

The WGSL syntax is inspired by WGSL (WebGPU). It has 24 attributes in the YotsubaShader.WgslSyntax package. The syntax you write with does not decide the output: the same shader compiles to any target.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

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.WgslSyntax;

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

    // Vertex index
    [@builtin_vertex_index] public uint VertexIndex;

    // Instance index
    [@builtin_instance_index] public uint InstanceIndex;

    // Clip distance
    [@builtin_clip_distances] public float ClipDistance;
}

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

    // Front-facing flag
    [@builtin_front_facing] public bool FrontFacingFlag;

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

    // Sample index
    [@builtin_sample_index] public uint SampleIndex;

    // Sample mask
    [@builtin_sample_mask] public uint SampleMask;

    // Primitive index
    [@builtin_primitive_index] public uint PrimitiveIndex;
}

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

    // Local invocation id
    [@builtin_local_invocation_id] public UInt3 LocalInvocationId;

    // Local invocation index
    [@builtin_local_invocation_index] public uint LocalInvocationIndex;

    // Workgroup id
    [@builtin_workgroup_id] public UInt3 WorkgroupId;

    // Number of workgroups
    [@builtin_num_workgroups] public UInt3 NumberOfWorkgroups;

    // Subgroup size
    [@builtin_subgroup_size] public uint SubgroupSize;

    // Subgroup invocation id
    [@builtin_subgroup_invocation_id] public UInt3 SubgroupInvocationId;

    // Subgroup id
    [@builtin_subgroup_id] public uint SubgroupId;

    // Number of subgroups
    [@builtin_num_subgroups] public uint NumberOfSubgroups;

    // Workgroup size (method attribute)
    [ShaderStage(Stage.Compute)]
    [@workgroup_size(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.WgslSyntax;
using YotsubaShader.WgslSyntax.Resources;

public struct Material
{
    public float Exposure;
}

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

    // Read/write storage buffer
    [storage(storage_use.read_write), @group(0), @binding(1)]
    public float[] Output;

    // Read-only storage buffer
    [storage(storage_use.read), @group(0), @binding(2)]
    public float[] Input;
}
using YotsubaShader.WgslSyntax;
using YotsubaShader.WgslSyntax.Resources;

public class Surface
{
    [@group(0), @binding(0)]
    public Texture2D Albedo;

    [@group(0), @binding(1)]
    public SamplerState Sampler;
}

Equivalents in the other syntaxes#

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

Built-in values#

ConceptWGSLHLSLGLSLMSLSPIR-V
Vertex stage
Clip-space position (vertex output)@builtin_positionSV_Positiongl_PositionpositionBuiltIn_Position
Vertex index@builtin_vertex_indexSV_VertexIDgl_VertexIndexvertex_idBuiltIn_VertexIndex
Instance index@builtin_instance_indexSV_InstanceIDgl_InstanceIndexinstance_idBuiltIn_InstanceIndex
Base vertex—SV_StartVertexLocationgl_BaseVertexbase_vertexBuiltIn_BaseVertex
Base instance—SV_StartInstanceLocationgl_BaseInstancebase_instanceBuiltIn_BaseInstance
Clip distance@builtin_clip_distancesSV_ClipDistanceNgl_ClipDistanceclip_distanceBuiltIn_ClipDistance
Render target layer—SV_RenderTargetArrayIndexgl_Layerrender_target_array_indexBuiltIn_Layer
Viewport index—SV_ViewportArrayIndexgl_ViewportIndexviewport_array_indexBuiltIn_ViewportIndex
Fragment stage
Fragment coordinate@builtin_positionSV_Positiongl_FragCoordpositionBuiltIn_FragCoord
Front-facing flag@builtin_front_facingSV_IsFrontFacegl_FrontFacingfront_facingBuiltIn_FrontFacing
Fragment depth (output)@builtin_frag_depthSV_Depthgl_FragDepthdepthBuiltIn_FragDepth
Conservative depth—SV_DepthGreaterEqual / SV_DepthLessEqual—depth("greater") / depth("less")—
Stencil reference (output)—SV_StencilRefgl_FragStencilRefARBstencilBuiltIn_FragStencilRef
Sample index@builtin_sample_indexSV_SampleIndexgl_SampleIDsample_idBuiltIn_SampleId
Sample mask@builtin_sample_maskSV_Coveragegl_SampleMask / gl_SampleMaskInsample_maskBuiltIn_SampleMask
Primitive index@builtin_primitive_indexSV_PrimitiveIDgl_PrimitiveIDprimitive_idBuiltIn_PrimitiveId
Barycentric coordinates—SV_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 id@builtin_global_invocation_idSV_DispatchThreadIDgl_GlobalInvocationIDthread_position_in_gridBuiltIn_GlobalInvocationId
Local invocation id@builtin_local_invocation_idSV_GroupThreadIDgl_LocalInvocationIDthread_position_in_threadgroupBuiltIn_LocalInvocationId
Local invocation index@builtin_local_invocation_indexSV_GroupIndexgl_LocalInvocationIndexthread_index_in_threadgroupBuiltIn_LocalInvocationIndex
Workgroup id@builtin_workgroup_idSV_GroupIDgl_WorkGroupIDthreadgroup_position_in_gridBuiltIn_WorkgroupId
Number of workgroups@builtin_num_workgroups—gl_NumWorkGroupsthreadgroups_per_gridBuiltIn_NumWorkgroups
Workgroup size (method attribute)@workgroup_sizenumthreadslayout_local_size——
Workgroup size (built-in value)——gl_WorkGroupSizethreads_per_threadgroupBuiltIn_WorkgroupSize
Subgroup size@builtin_subgroup_size—gl_SubgroupSizethreads_per_simdgroupBuiltIn_SubgroupSize
Subgroup invocation id@builtin_subgroup_invocation_id—gl_SubgroupInvocationIDthread_index_in_simdgroupBuiltIn_SubgroupInvocationId
Subgroup id@builtin_subgroup_id—gl_SubgroupIDsimdgroup_index_in_threadgroupBuiltIn_SubgroupId
Number of subgroups@builtin_num_subgroups—gl_NumSubgroupssimdgroups_per_threadgroupBuiltIn_NumSubgroups

Resources#

ConceptWGSLHLSLGLSLMSLSPIR-V
Uniform bufferuniformcbuffer, ConstantBuffer<T>uniformconstantUniform
Read/write storage bufferstorage(storage_use.read_write)RWStructuredBuffer<T>bufferdeviceStorageBuffer
Read-only storage bufferstorage(storage_use.read)StructuredBuffer<T>bufferdevice(readOnly: true)StorageBuffer
Binding slot@group(s) + @binding(n)register(RegisterPrefix.b, n)layout(set, binding)buffer(n), texture(n), sampler(n)DescriptorSet(s) + Binding(n)
Texture slot@group(s) + @binding(n)register(RegisterPrefix.t, n)layout(set, binding)texture(n)DescriptorSet(s) + Binding(n)
Sampler slot@group(s) + @binding(n)register(RegisterPrefix.s, n)layout(set, binding)sampler(n)DescriptorSet(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.WgslSyntax;

public struct InputExamples
{
    // Front-facing flag
    [@builtin_front_facing] public bool FrontFacingFlag;
    // Global invocation id
    [@builtin_global_invocation_id]
    public UInt3 GlobalInvocationId;
    // Instance index
    [@builtin_instance_index] public uint InstanceIndex;
    // Local invocation id
    [@builtin_local_invocation_id]
    public UInt3 LocalInvocationId;
    // Local invocation index
    [@builtin_local_invocation_index]
    public uint LocalInvocationIndex;
    // Number of subgroups
    [@builtin_num_subgroups] public uint NumberOfSubgroups;
    // Number of workgroups
    [@builtin_num_workgroups] public UInt3 NumberOfWorkgroups;
    // Primitive index
    [@builtin_primitive_index] public uint PrimitiveIndex;
    // Sample index
    [@builtin_sample_index] public uint SampleIndex;
    // Subgroup id
    [@builtin_subgroup_id] public uint SubgroupId;
    // Subgroup invocation id
    [@builtin_subgroup_invocation_id]
    public UInt3 SubgroupInvocationId;
    // Subgroup size
    [@builtin_subgroup_size] public uint SubgroupSize;
    // Vertex index
    [@builtin_vertex_index] public uint VertexIndex;
    // Workgroup id
    [@builtin_workgroup_id] public UInt3 WorkgroupId;
}

Input and output attributes#

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

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public struct InputOutputExamples
{
    // Clip-space position (vertex output)
    [@builtin_position] public Vector4 ClipSpacePosition;
    // Sample mask
    [@builtin_sample_mask] public uint SampleMask;
    [@location(0)] public Vector4 Value3;
}

Output attributes#

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

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public struct OutputExamples
{
    // Clip distance
    [@builtin_clip_distances] public float ClipDistance;
    // Fragment depth (output)
    [@builtin_frag_depth] public float FragmentDepth;
}

Method attributes#

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

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public class MethodExamples
{
    [ShaderStage(Stage.Compute)]
    [@workgroup_size(8)]
    public void Workgroup_sizeExample() { }
}

Resource attributes#

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

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;
using YotsubaShader.WgslSyntax.Resources;

public class ResourceExamples
{
    [@binding(0)] public float Value1;
    [@group(0)] public float Value2;
    [storage(storage_use.read_write)] public float Value3;
    [uniform] public float Value4;
}

Supporting types#

Structs, classes and enums used together with the attributes.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public class Types
{
    public YotsubaShader.WgslSyntax.Types.__frexp_result_f16 __frexp_result_f16Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_f32 __frexp_result_f32Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_vec2_f16 __frexp_result_vec2_f16Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_vec2_f32 __frexp_result_vec2_f32Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_vec3_f16 __frexp_result_vec3_f16Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_vec3_f32 __frexp_result_vec3_f32Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_vec4_f16 __frexp_result_vec4_f16Value;
    public YotsubaShader.WgslSyntax.Types.__frexp_result_vec4_f32 __frexp_result_vec4_f32Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_f16 __modf_result_f16Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_f32 __modf_result_f32Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_vec2_f16 __modf_result_vec2_f16Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_vec2_f32 __modf_result_vec2_f32Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_vec3_f16 __modf_result_vec3_f16Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_vec3_f32 __modf_result_vec3_f32Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_vec4_f16 __modf_result_vec4_f16Value;
    public YotsubaShader.WgslSyntax.Types.__modf_result_vec4_f32 __modf_result_vec4_f32Value;
    public YotsubaShader.WgslSyntax.Types.mat2x2<float> mat2x2GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat2x3<float> mat2x3GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat2x4<float> mat2x4GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat3x2<float> mat3x2GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat3x3<float> mat3x3GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat3x4<float> mat3x4GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat4x2<float> mat4x2GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat4x3<float> mat4x3GenericValue;
    public YotsubaShader.WgslSyntax.Types.mat4x4<float> mat4x4GenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.sampler SamplerValue;
    public YotsubaShader.WgslSyntax.Resources.Types.sampler_comparison Sampler_comparisonValue;
    public YotsubaShader.WgslSyntax.Resources.storage_use Storage_useValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_1d<float> texture_1dGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_2d<float> texture_2dGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_2d_array<float> texture_2d_arrayGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_3d<float> texture_3dGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_cube<float> texture_cubeGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_cube_array<float> texture_cube_arrayGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_depth_2d Texture_depth_2dValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_depth_2d_array Texture_depth_2d_arrayValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_depth_cube Texture_depth_cubeValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_depth_cube_array Texture_depth_cube_arrayValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_depth_multisampled_2d Texture_depth_multisampled_2dValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_external Texture_externalValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_multisampled_2d<float> texture_multisampled_2dGenericValue;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_storage_1d<T1, T2> Texture_storage_1d<T1, T2>Value;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_storage_2d<T1, T2> Texture_storage_2d<T1, T2>Value;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_storage_2d_array<T1, T2> Texture_storage_2d_array<T1, T2>Value;
    public YotsubaShader.WgslSyntax.Resources.Types.texture_storage_3d<T1, T2> Texture_storage_3d<T1, T2>Value;
    public YotsubaShader.WgslSyntax.Types.vec2<float> vec2GenericValue;
    public YotsubaShader.WgslSyntax.Types.vec3<float> vec3GenericValue;
    public YotsubaShader.WgslSyntax.Types.vec4<float> vec4GenericValue;
}

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