El catálogo de atributos de WGSL

Los atributos son la parte de WGSL que no se parece a ningún lenguaje de propósito general: son la interfaz declarativa entre el shader y todo lo que hay fuera de él. Unos conectan con la API, otros colocan bytes en memoria, y unos pocos hablan directamente con el compilador para pedirle que se contenga. Conocer los quince de golpe cuesta una lectura y evita buscar la sintaxis quince veces.

La gramática y el mapa

Un atributo es una arroba, un nombre y, si lo lleva, una lista de argumentos entre paréntesis. Se colocan delante del elemento que decoran y se pueden encadenar varios en la misma línea o en líneas distintas.

La regla general sobre los argumentos: casi todos exigen una expresión de tiempo de compilación, es decir, literales, const y operaciones entre ellos. La excepción es @workgroup_size, que además admite expresiones override, y esa excepción es la que permite decidir el tamaño de grupo al crear el pipeline.

override TAM : u32 = 64u;

@compute @workgroup_size(TAM)       // legal: override
fn cs() { }

// @group(TAM) ...                  // ERROR: @group exige constante

Los que conectan con la API —@location, @builtin, @group, @binding— tienen lección propia. Los otros cuatro que merecen desarrollo son los que siguen.

@align y @size: colocar bytes a mano

Las reglas de disposición del lenguaje producen desplazamientos automáticos. Estos dos atributos permiten anularlos hacia arriba, nunca hacia abajo.

@align(n) fuerza que ese miembro empiece en un múltiplo de n. El valor tiene que ser potencia de dos y no menor que la alineación natural del tipo: puedes alinear un f32 a 16, pero no puedes alinear un vec4f a 4.

struct Bloque {
  a : f32,              // offset 0
  @align(16) b : f32,   // offset 16 en lugar de 4
};                      // AlignOf 16, SizeOf 32

@size(n) fuerza el espacio que ese miembro ocupa dentro de la struct, que tiene que ser mayor o igual que su tamaño natural. No cambia el tipo ni lo que el shader lee: solo empuja al miembro siguiente.

struct Bloque2 {
  @size(16) v : vec3f,   // ocupa 16 aunque un vec3f mida 12
  f : f32,               // offset 16, no 12
};                       // SizeOf 32

La diferencia entre los dos es la dirección en la que empujan: @align mueve el principio de este miembro, @size mueve el principio del siguiente. Los dos afectan al tamaño y a la alineación de la struct que los contiene, con las mismas reglas de siempre.

Su uso real no es artístico: es hacer que una struct de WGSL coincida byte a byte con una estructura que ya existe en otro sitio, típicamente un formato de fichero, un layout impuesto por una librería o una struct que también consume código de CPU.

@interpolate e @invariant

@interpolate decide cómo viaja un valor de la etapa de vértices a la de fragmentos. Acepta un tipo —perspective, linear o flat— y opcionalmente un muestreo —center, centroid o sample, y para flat los valores first y either.

struct SalidaVS {
  @builtin(position)                     clip   : vec4f,
  @location(0)                           uv     : vec2f,   // perspective, center
  @location(1) @interpolate(flat)        idMat  : u32,
  @location(2) @interpolate(linear)      lineal : f32,
  @location(3) @interpolate(perspective, sample) porMuestra : vec3f,
};

Sin atributo, el comportamiento es perspective con muestreo center, que es lo que quieres el 95 % de las veces. Los tipos enteros obligan a flat. Y el atributo tiene que ser idéntico en el lado del vertex y en el del fragment, o el pipeline no se crea.

@invariant es otra cosa y solo se aplica al @builtin(position) de salida de un vertex shader. Le pide al compilador que el cálculo de esa posición produzca exactamente los mismos bits que produciría cualquier otro shader que la calcule con la misma expresión y los mismos datos.

@vertex
fn vsProfundidad(@location(0) p : vec3f) -> @invariant @builtin(position) vec4f {
  return camara.viewProj * modelo.matriz * vec4f(p, 1.0);
}

Los que hablan con el compilador

@must_use marca una función cuyo resultado no se puede ignorar. Llamarla como si fuera un procedimiento es un error de compilación:

@must_use
fn normalizarSeguro(v : vec3f) -> vec3f {
  let l = length(v);
  return select(vec3f(0.0, 0.0, 1.0), v / l, l > 1e-6);
}

Sirve para funciones puras y caras cuyo valor es lo único que producen. Si de verdad quieres descartar el resultado, la asignación de descarte lo permite: _ = normalizarSeguro(v);.

@diagnostic ajusta la severidad de una regla del compilador en un ámbito concreto, y hoy la única regla estándar es derivative_uniformity. A nivel de módulo se escribe como directiva; sobre una función o un bloque, como atributo:

@fragment
@diagnostic(warning, derivative_uniformity)
fn fs(entrada : Entrada) -> @location(0) vec4f {
  // aqui el analisis de uniformidad avisa en lugar de fallar
  return vec4f(1.0);
}

Bajar la severidad no cambia el comportamiento del hardware: cambia si el compilador te deja pasar. Si el análisis tenía razón, el resultado sigue siendo indeterminado; lo único que has hecho es asumir tú la responsabilidad.

@id(n) da un identificador numérico a una override para poder especificarla por número en vez de por nombre al crear el pipeline. Los números tienen que ser únicos en el módulo.