Yotsuba ShaderAprende

Sintaxis HLSL

3 min de lectura

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

La sintaxis HLSL está inspirada en HLSL (Direct3D). Tiene 31 atributos en el paquete YotsubaShader.HlslSyntax. La sintaxis con la que escribes no decide el resultado: el mismo shader compila a cualquier destino.

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

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

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

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

    // Índice de instancia
    [SV_InstanceID] public uint InstanceIndex;

    // Vértice base
    [SV_StartVertexLocation] public uint BaseVertex;

    // Instancia base
    [SV_StartInstanceLocation] public uint BaseInstance;

    // Distancia de clip
    [SV_ClipDistanceN] public float ClipDistance;

    // Capa del render target
    [SV_RenderTargetArrayIndex] public uint RenderTargetLayer;

    // Índice de viewport
    [SV_ViewportArrayIndex] public uint ViewportIndex;
}

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

    // Indicador de cara frontal
    [SV_IsFrontFace] public bool FrontFacingFlag;

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

    // Profundidad conservadora
    [SV_DepthGreaterEqual] public float ConservativeDepth;

    // Profundidad conservadora
    [SV_DepthLessEqual] public float ConservativeDepth2;

    // Referencia de stencil (salida)
    [SV_StencilRef] public uint StencilReference;

    // Índice de muestra
    [SV_SampleIndex] public uint SampleIndex;

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

    // Índice de primitiva
    [SV_PrimitiveID] public uint PrimitiveIndex;

    // Coordenadas baricéntricas
    [SV_Barycentrics] public Vector4 BarycentricCoordinates;
}

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

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

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

    // Id de workgroup
    [SV_GroupID] public UInt3 WorkgroupId;

    // Tamaño del workgroup (atributo de método)
    [ShaderStage(Stage.Compute)]
    [numthreads(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.HlslSyntax;
using YotsubaShader.HlslSyntax.Resources;

public struct Material
{
    public float Exposure;
}

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

    // Storage buffer de lectura y escritura
    [register(RegisterPrefix.u, 0)]
    public RWStructuredBuffer<float> Output;

    // Storage buffer de solo lectura
    [register("t0")]
    public StructuredBuffer<float> Input;
}
using YotsubaShader.HlslSyntax;
using YotsubaShader.HlslSyntax.Resources;

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

    // El mismo registro, escrito como cadena: letra + número
    [register("s0")]
    public SamplerState Sampler;
}

Equivalencias en las otras sintaxis#

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

Valores integrados#

ConceptoHLSLGLSLMSLSPIR-VWGSL
Etapa de vertex
Posición en clip space (salida de vertex)SV_Positiongl_PositionpositionBuiltIn_Position@builtin_position
Índice de vérticeSV_VertexIDgl_VertexIndexvertex_idBuiltIn_VertexIndex@builtin_vertex_index
Índice de instanciaSV_InstanceIDgl_InstanceIndexinstance_idBuiltIn_InstanceIndex@builtin_instance_index
Vértice baseSV_StartVertexLocationgl_BaseVertexbase_vertexBuiltIn_BaseVertex—
Instancia baseSV_StartInstanceLocationgl_BaseInstancebase_instanceBuiltIn_BaseInstance—
Distancia de clipSV_ClipDistanceNgl_ClipDistanceclip_distanceBuiltIn_ClipDistance@builtin_clip_distances
Capa del render targetSV_RenderTargetArrayIndexgl_Layerrender_target_array_indexBuiltIn_Layer—
Índice de viewportSV_ViewportArrayIndexgl_ViewportIndexviewport_array_indexBuiltIn_ViewportIndex—
Etapa de fragment
Coordenada de fragmentoSV_Positiongl_FragCoordpositionBuiltIn_FragCoord@builtin_position
Indicador de cara frontalSV_IsFrontFacegl_FrontFacingfront_facingBuiltIn_FrontFacing@builtin_front_facing
Profundidad del fragmento (salida)SV_Depthgl_FragDepthdepthBuiltIn_FragDepth@builtin_frag_depth
Profundidad conservadoraSV_DepthGreaterEqual / SV_DepthLessEqual—depth("greater") / depth("less")——
Referencia de stencil (salida)SV_StencilRefgl_FragStencilRefARBstencilBuiltIn_FragStencilRef—
Índice de muestraSV_SampleIndexgl_SampleIDsample_idBuiltIn_SampleId@builtin_sample_index
Máscara de muestrasSV_Coveragegl_SampleMask / gl_SampleMaskInsample_maskBuiltIn_SampleMask@builtin_sample_mask
Índice de primitivaSV_PrimitiveIDgl_PrimitiveIDprimitive_idBuiltIn_PrimitiveId@builtin_primitive_index
Coordenadas baricéntricasSV_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 globalSV_DispatchThreadIDgl_GlobalInvocationIDthread_position_in_gridBuiltIn_GlobalInvocationId@builtin_global_invocation_id
Id de invocación localSV_GroupThreadIDgl_LocalInvocationIDthread_position_in_threadgroupBuiltIn_LocalInvocationId@builtin_local_invocation_id
Índice de invocación localSV_GroupIndexgl_LocalInvocationIndexthread_index_in_threadgroupBuiltIn_LocalInvocationIndex@builtin_local_invocation_index
Id de workgroupSV_GroupIDgl_WorkGroupIDthreadgroup_position_in_gridBuiltIn_WorkgroupId@builtin_workgroup_id
Número de workgroups—gl_NumWorkGroupsthreadgroups_per_gridBuiltIn_NumWorkgroups@builtin_num_workgroups
Tamaño del workgroup (atributo de método)numthreadslayout_local_size——@workgroup_size
Tamaño del workgroup (valor integrado)—gl_WorkGroupSizethreads_per_threadgroupBuiltIn_WorkgroupSize—
Tamaño del subgrupo—gl_SubgroupSizethreads_per_simdgroupBuiltIn_SubgroupSize@builtin_subgroup_size
Id de invocación del subgrupo—gl_SubgroupInvocationIDthread_index_in_simdgroupBuiltIn_SubgroupInvocationId@builtin_subgroup_invocation_id
Id del subgrupo—gl_SubgroupIDsimdgroup_index_in_threadgroupBuiltIn_SubgroupId@builtin_subgroup_id
Número de subgrupos—gl_NumSubgroupssimdgroups_per_threadgroupBuiltIn_NumSubgroups@builtin_num_subgroups

Recursos#

ConceptoHLSLGLSLMSLSPIR-VWGSL
Uniform buffercbuffer, ConstantBuffer<T>uniformconstantUniformuniform
Storage buffer de lectura y escrituraRWStructuredBuffer<T>bufferdeviceStorageBufferstorage(storage_use.read_write)
Storage buffer de solo lecturaStructuredBuffer<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)

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

public struct InputExamples
{
    // Coordenadas baricéntricas
    [SV_Barycentrics] public Vector4 BarycentricCoordinates;
    // Id de invocación global
    [SV_DispatchThreadID] public UInt3 GlobalInvocationId;
    // Id de workgroup
    [SV_GroupID] public UInt3 WorkgroupId;
    // Índice de invocación local
    [SV_GroupIndex] public uint LocalInvocationIndex;
    // Id de invocación local
    [SV_GroupThreadID] public UInt3 LocalInvocationId;
    // Índice de instancia
    [SV_InstanceID] public uint InstanceIndex;
    // Indicador de cara frontal
    [SV_IsFrontFace] public bool FrontFacingFlag;
    // Índice de primitiva
    [SV_PrimitiveID] public uint PrimitiveIndex;
    // Índice de muestra
    [SV_SampleIndex] public uint SampleIndex;
    // Instancia base
    [SV_StartInstanceLocation] public uint BaseInstance;
    // Vértice base
    [SV_StartVertexLocation] public uint BaseVertex;
    // Índice de vértice
    [SV_VertexID] public uint VertexIndex;
}

Atributos de entrada y salida#

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

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;
    // Máscara de muestras
    [SV_Coverage] public uint SampleMask;
    // Posición en clip space (salida de vertex)
    [SV_Position] public Vector4 ClipSpacePosition;
    // Capa del render target
    [SV_RenderTargetArrayIndex] public uint RenderTargetLayer;
    // Índice de viewport
    [SV_ViewportArrayIndex] public uint ViewportIndex;
    [TANGENT] public Vector4 Value10;
    [TEXCOORD] public Vector4 Value11;
}

Atributos de salida#

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

using YotsubaShader.Language;
using YotsubaShader.HlslSyntax;

public struct OutputExamples
{
    // Profundidad del fragmento (salida)
    [SV_Depth] public float FragmentDepth;
    // Profundidad conservadora
    [SV_DepthGreaterEqual] public float ConservativeDepth;
    // Profundidad conservadora
    [SV_DepthLessEqual] public float ConservativeDepth2;
    // Referencia de stencil (salida)
    [SV_StencilRef] public uint StencilReference;
    [SV_Target] public Vector4 Value5;
}

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

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

Atributos de recurso#

Declaran uniforms, buffers, texturas, samplers y ranuras.

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

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

    // La sobrecarga con cadena: letra + número
    [register("b1")]
    public float Value3;
}

Tipos de apoyo#

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

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

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