Yotsuba ShaderAprende

Sintaxis WGSL

3 min de lectura

Todos los atributos de la sintaxis WGSL, con ejemplos en C#.

La sintaxis WGSL está inspirada en WGSL (WebGPU). Tiene 24 atributos en el paquete YotsubaShader.WgslSyntax. La sintaxis con la que escribes no decide el resultado: el mismo shader compila a cualquier destino.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public struct VertexOutput
{
    [@builtin_position]
    public Vector4 Position;
}

Valores integrados por etapa#

Todos los valores integrados que declara la sintaxis, agrupados por la etapa que los usa.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

// Etapa de vertex
public struct VertexBuiltIns
{
    // Posición en clip space (salida de vertex)
    [@builtin_position] public Vector4 ClipSpacePosition;

    // Índice de vértice
    [@builtin_vertex_index] public uint VertexIndex;

    // Índice de instancia
    [@builtin_instance_index] public uint InstanceIndex;

    // Distancia de clip
    [@builtin_clip_distances] public float ClipDistance;
}

// Etapa de fragment
public struct FragmentBuiltIns
{
    // Coordenada de fragmento
    [@builtin_position] public Vector4 FragmentCoordinate;

    // Indicador de cara frontal
    [@builtin_front_facing] public bool FrontFacingFlag;

    // Profundidad del fragmento (salida)
    [@builtin_frag_depth] public float FragmentDepth;

    // Índice de muestra
    [@builtin_sample_index] public uint SampleIndex;

    // Máscara de muestras
    [@builtin_sample_mask] public uint SampleMask;

    // Índice de primitiva
    [@builtin_primitive_index] public uint PrimitiveIndex;
}

// Etapa de compute
public class ComputeBuiltIns
{
    // Id de invocación global
    [@builtin_global_invocation_id] public UInt3 GlobalInvocationId;

    // Id de invocación local
    [@builtin_local_invocation_id] public UInt3 LocalInvocationId;

    // Índice de invocación local
    [@builtin_local_invocation_index] public uint LocalInvocationIndex;

    // Id de workgroup
    [@builtin_workgroup_id] public UInt3 WorkgroupId;

    // Número de workgroups
    [@builtin_num_workgroups] public UInt3 NumberOfWorkgroups;

    // Tamaño del subgrupo
    [@builtin_subgroup_size] public uint SubgroupSize;

    // Id de invocación del subgrupo
    [@builtin_subgroup_invocation_id] public UInt3 SubgroupInvocationId;

    // Id del subgrupo
    [@builtin_subgroup_id] public uint SubgroupId;

    // Número de subgrupos
    [@builtin_num_subgroups] public uint NumberOfSubgroups;

    // Tamaño del workgroup (atributo de método)
    [ShaderStage(Stage.Compute)]
    [@workgroup_size(8, 8, 1)]
    public void Compute() { }
}

Recursos y ranuras#

Buffers uniformes, buffers de almacenamiento, texturas y samplers, cada uno con su ranura escrita en esta sintaxis.

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

public struct Material
{
    public float Exposure;
}

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

    // Storage buffer de lectura y escritura
    [storage(storage_use.read_write), @group(0), @binding(1)]
    public float[] Output;

    // Storage buffer de solo lectura
    [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;
}

Equivalencias en las otras sintaxis#

El mismo concepto en WGSL y en las otras cuatro sintaxis. Un guion significa que esa sintaxis no tiene forma de escribirlo.

Valores integrados#

ConceptoWGSLHLSLGLSLMSLSPIR-V
Etapa de vertex
Posición en clip space (salida de vertex)@builtin_positionSV_Positiongl_PositionpositionBuiltIn_Position
Índice de vértice@builtin_vertex_indexSV_VertexIDgl_VertexIndexvertex_idBuiltIn_VertexIndex
Índice de instancia@builtin_instance_indexSV_InstanceIDgl_InstanceIndexinstance_idBuiltIn_InstanceIndex
Vértice base—SV_StartVertexLocationgl_BaseVertexbase_vertexBuiltIn_BaseVertex
Instancia base—SV_StartInstanceLocationgl_BaseInstancebase_instanceBuiltIn_BaseInstance
Distancia de clip@builtin_clip_distancesSV_ClipDistanceNgl_ClipDistanceclip_distanceBuiltIn_ClipDistance
Capa del render target—SV_RenderTargetArrayIndexgl_Layerrender_target_array_indexBuiltIn_Layer
Índice de viewport—SV_ViewportArrayIndexgl_ViewportIndexviewport_array_indexBuiltIn_ViewportIndex
Etapa de fragment
Coordenada de fragmento@builtin_positionSV_Positiongl_FragCoordpositionBuiltIn_FragCoord
Indicador de cara frontal@builtin_front_facingSV_IsFrontFacegl_FrontFacingfront_facingBuiltIn_FrontFacing
Profundidad del fragmento (salida)@builtin_frag_depthSV_Depthgl_FragDepthdepthBuiltIn_FragDepth
Profundidad conservadora—SV_DepthGreaterEqual / SV_DepthLessEqual—depth("greater") / depth("less")—
Referencia de stencil (salida)—SV_StencilRefgl_FragStencilRefARBstencilBuiltIn_FragStencilRef
Índice de muestra@builtin_sample_indexSV_SampleIndexgl_SampleIDsample_idBuiltIn_SampleId
Máscara de muestras@builtin_sample_maskSV_Coveragegl_SampleMask / gl_SampleMaskInsample_maskBuiltIn_SampleMask
Índice de primitiva@builtin_primitive_indexSV_PrimitiveIDgl_PrimitiveIDprimitive_idBuiltIn_PrimitiveId
Coordenadas baricéntricas—SV_Barycentricsgl_BaryCoordEXTbarycentric_coordBuiltIn_BaryCoord
Coordenadas baricéntricas (sin perspectiva)——gl_BaryCoordNoPerspEXT—BuiltIn_BaryCoordNoPersp
Invocación auxiliar——gl_HelperInvocation—BuiltIn_HelperInvocation
Posición de muestra——gl_SamplePosition—BuiltIn_SamplePosition
Etapa de compute
Id de invocación global@builtin_global_invocation_idSV_DispatchThreadIDgl_GlobalInvocationIDthread_position_in_gridBuiltIn_GlobalInvocationId
Id de invocación local@builtin_local_invocation_idSV_GroupThreadIDgl_LocalInvocationIDthread_position_in_threadgroupBuiltIn_LocalInvocationId
Índice de invocación local@builtin_local_invocation_indexSV_GroupIndexgl_LocalInvocationIndexthread_index_in_threadgroupBuiltIn_LocalInvocationIndex
Id de workgroup@builtin_workgroup_idSV_GroupIDgl_WorkGroupIDthreadgroup_position_in_gridBuiltIn_WorkgroupId
Número de workgroups@builtin_num_workgroups—gl_NumWorkGroupsthreadgroups_per_gridBuiltIn_NumWorkgroups
Tamaño del workgroup (atributo de método)@workgroup_sizenumthreadslayout_local_size——
Tamaño del workgroup (valor integrado)——gl_WorkGroupSizethreads_per_threadgroupBuiltIn_WorkgroupSize
Tamaño del subgrupo@builtin_subgroup_size—gl_SubgroupSizethreads_per_simdgroupBuiltIn_SubgroupSize
Id de invocación del subgrupo@builtin_subgroup_invocation_id—gl_SubgroupInvocationIDthread_index_in_simdgroupBuiltIn_SubgroupInvocationId
Id del subgrupo@builtin_subgroup_id—gl_SubgroupIDsimdgroup_index_in_threadgroupBuiltIn_SubgroupId
Número de subgrupos@builtin_num_subgroups—gl_NumSubgroupssimdgroups_per_threadgroupBuiltIn_NumSubgroups

Recursos#

ConceptoWGSLHLSLGLSLMSLSPIR-V
Uniform bufferuniformcbuffer, ConstantBuffer<T>uniformconstantUniform
Storage buffer de lectura y escriturastorage(storage_use.read_write)RWStructuredBuffer<T>bufferdeviceStorageBuffer
Storage buffer de solo lecturastorage(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)

Atributos#

Los atributos que declara el paquete, en grupos y aplicados a miembros reales.

Atributos de entrada#

Se aplican a campos, parámetros y propiedades que reciben valores del pipeline.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public struct InputExamples
{
    // Indicador de cara frontal
    [@builtin_front_facing] public bool FrontFacingFlag;
    // Id de invocación global
    [@builtin_global_invocation_id]
    public UInt3 GlobalInvocationId;
    // Índice de instancia
    [@builtin_instance_index] public uint InstanceIndex;
    // Id de invocación local
    [@builtin_local_invocation_id]
    public UInt3 LocalInvocationId;
    // Índice de invocación local
    [@builtin_local_invocation_index]
    public uint LocalInvocationIndex;
    // Número de subgrupos
    [@builtin_num_subgroups] public uint NumberOfSubgroups;
    // Número de workgroups
    [@builtin_num_workgroups] public UInt3 NumberOfWorkgroups;
    // Índice de primitiva
    [@builtin_primitive_index] public uint PrimitiveIndex;
    // Índice de muestra
    [@builtin_sample_index] public uint SampleIndex;
    // Id del subgrupo
    [@builtin_subgroup_id] public uint SubgroupId;
    // Id de invocación del subgrupo
    [@builtin_subgroup_invocation_id]
    public UInt3 SubgroupInvocationId;
    // Tamaño del subgrupo
    [@builtin_subgroup_size] public uint SubgroupSize;
    // Índice de vértice
    [@builtin_vertex_index] public uint VertexIndex;
    // Id de workgroup
    [@builtin_workgroup_id] public UInt3 WorkgroupId;
}

Atributos de entrada y salida#

Se aplican a valores que se pueden recibir o producir, según la etapa.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public struct InputOutputExamples
{
    // Posición en clip space (salida de vertex)
    [@builtin_position] public Vector4 ClipSpacePosition;
    // Máscara de muestras
    [@builtin_sample_mask] public uint SampleMask;
    [@location(0)] public Vector4 Value3;
}

Atributos de salida#

Se aplican a campos, parámetros y valores de retorno que produce la etapa.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

public struct OutputExamples
{
    // Distancia de clip
    [@builtin_clip_distances] public float ClipDistance;
    // Profundidad del fragmento (salida)
    [@builtin_frag_depth] public float FragmentDepth;
}

Atributos de método#

Se aplican a métodos, por ejemplo para fijar el tamaño del grupo de trabajo de un compute.

using YotsubaShader.Language;
using YotsubaShader.WgslSyntax;

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

Atributos de recurso#

Declaran uniforms, buffers, texturas, samplers y ranuras.

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;
}

Tipos de apoyo#

Structs, clases y enums que se usan junto con los atributos.

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;
}

Las otras sintaxis: HLSL, GLSL, MSL, SPIR-V.