Los builtins de vértice y de fragmento

Un builtin es un valor que no viene de ningún buffer que tú hayas creado: lo pone el hardware. Son la parte del shader que conecta con el rasterizador y con el ensamblador de primitivas, y saber exactamente de dónde sale cada número es lo que separa reconstruir la posición del mundo desde un fragmento en tres líneas de pasarse una tarde con las coordenadas del revés.

El catálogo

clip_distances es el único que necesita permiso: requiere enable clip_distances; en el shader y la feature clip-distances en el dispositivo. Sirve para recortar geometría contra planos arbitrarios, que es lo que usa un renderer para los reflejos planos y las secciones.

vertex_index e instance_index

Los dos son contadores que produce el ensamblador de primitivas, y de dónde sale su valor depende del comando de dibujado.

En un dibujado no indexado, vertex_index empieza en el firstVertex que pasaste y avanza de uno en uno:

pase.draw(3, 1, 100, 0);    // vertex_index toma los valores 100, 101, 102

En un dibujado indexado, vertex_index es el valor leído del índice más el baseVertex, que puede ser negativo:

pase.drawIndexed(6, 1, 0, 500, 0);   // vertex_index = indice + 500

instance_index empieza siempre en el firstInstance del comando y avanza de uno en uno hasta completar el número de instancias.

La consecuencia útil de que vertex_index exista es que se puede dibujar sin buffers de vértices. El triángulo que cubre la pantalla entera para un pase de post-proceso es el caso canónico y no necesita ninguna geometría:

@vertex
fn vsPantalla(@builtin(vertex_index) i : u32) -> @builtin(position) vec4f {
  // Un unico triangulo grande que cubre todo el cuadrado de clip.
  var p = array<vec2f, 3>(
    vec2f(-1.0, -1.0),
    vec2f( 3.0, -1.0),
    vec2f(-1.0,  3.0),
  );
  return vec4f(p[i], 0.0, 1.0);
}

Y la consecuencia útil de instance_index es que es el índice natural para leer datos por objeto desde un storage buffer, sin atributos por instancia y sin bind groups por objeto.

position, dos builtins con el mismo nombre

Se llaman igual y son cosas distintas. Confundirlos es el error clásico de quien viene de GLSL, donde tenían nombres diferentes.

En la salida del vertex shader es la posición de clip: el resultado de multiplicar la posición del modelo por la matriz combinada, sin dividir por w. El hardware hace después tres cosas con ella: recorta la primitiva contra el volumen de visión, divide los tres primeros componentes por el cuarto, y mapea el resultado al viewport.

En la entrada del fragment shader es la coordenada de framebuffer, y sus cuatro componentes significan lo siguiente:

• x e y son píxeles, con el origen en la esquina superior izquierda y el centro del píxel en los medios: el primer píxel tiene coordenada (0.5, 0.5).
• z es la profundidad ya mapeada al rango de profundidad del viewport, normalmente entre 0 y 1. Es exactamente el valor que se compara contra el depth buffer.
• w es el recíproco de la w de clip, es decir, 1.0 / clip.w.

Ese último componente es el regalo escondido de la etapa. Con una matriz de proyección en perspectiva estándar, clip.w vale la distancia a la cámara a lo largo del eje de vista, así que:

@fragment
fn fs(@builtin(position) frag : vec4f) -> @location(0) vec4f {
  let profundidadLineal = 1.0 / frag.w;     // distancia en unidades de vista
  let niebla = 1.0 - exp(-profundidadLineal * 0.02);
  return vec4f(vec3f(niebla), 1.0);
}

Sin uniforms, sin varyings y sin leer el depth buffer. La profundidad lineal es una división.

Y la coordenada de pantalla normalizada sale igual de barata, siempre que sepas el tamaño del target:

let uv = frag.xy / vec2f(ajustes.tamanoPantalla);      // 0..1, origen arriba a la izquierda
let ndc = vec2f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0);   // -1..1, con la Y dada la vuelta

El cambio de signo de la Y es obligatorio y es la causa de la mitad de los efectos de pantalla completa que salen invertidos: en coordenadas de framebuffer la Y crece hacia abajo, y en coordenadas normalizadas de dispositivo crece hacia arriba.

Los builtins de cobertura y la salida

front_facing es un bool que dice si el triángulo se está viendo por su cara delantera, según el sentido de giro que declaraste en primitive.frontFace —'ccw' por defecto—. Su uso canónico es dar la vuelta a la normal para materiales de dos caras:

let n = select(-normalInterpolada, normalInterpolada, entrada.frontal);

sample_index es el índice de la muestra que se está sombreando cuando hay multimuestreo y el shader se ejecuta por muestra. Leerlo tiene una consecuencia importante: fuerza el sombreado por muestra, con lo que el fragment shader pasa de ejecutarse una vez por píxel a ejecutarse una vez por muestra, y en 4x eso es cuatro veces el coste.

sample_mask es una máscara de bits, uno por muestra. Como entrada dice qué muestras cubre la primitiva en ese píxel; como salida permite anular la escritura de muestras concretas, que es la base del recorte suave y del antialiasing de transparencias por cobertura. Si el pipeline tiene alphaToCoverageEnabled, escribir sample_mask desde el shader no está permitido: las dos cosas compiten por lo mismo.

frag_depth sustituye la profundidad interpolada por una calculada por ti. Su valor se acota al rango de profundidad del viewport, y escribirlo tiene un coste real que la lección de fragment shaders desarrolla: desactiva la prueba de profundidad temprana.

struct SalidaFS {
  @location(0) color : vec4f,
  @builtin(frag_depth) profundidad : f32,
};