@group y @binding: las dos coordenadas de un recurso

Un recurso en WGSL no se busca por nombre: se declara en unas coordenadas. @group dice a qué conjunto pertenece y @binding en qué ranura de ese conjunto está, y esas dos cifras son el único vínculo entre el texto del shader y los objetos que crea la API. El shader no sabe nada de buffers ni de texturas concretas; sabe que en el grupo 1, ranura 2, va a haber algo de un tipo determinado.

Las dos coordenadas

Las llevan todas las variables de módulo de los espacios uniform, storage y handle, y solo esas. Una var<private> no las lleva y no puede llevarlas.

struct Camara {
  viewProj : mat4x4f,
  posicion : vec3f,
  tiempo   : f32,
};

@group(0) @binding(0) var<uniform> camara : Camara;
@group(0) @binding(1) var muestreo : sampler;
@group(0) @binding(2) var entorno : texture_cube<f32>;

@group(1) @binding(0) var<storage, read> instancias : array<Instancia>;
@group(1) @binding(1) var<storage, read_write> visibles : array<u32>;

@group(2) @binding(0) var albedo : texture_2d<f32>;
@group(2) @binding(1) var normalMap : texture_2d<f32>;

El número de @binding no tiene que ser consecutivo ni empezar en cero; solo tiene que ser único dentro de su grupo. El de @group está acotado por maxBindGroups, con un mínimo garantizado de 4, así que los índices válidos en el caso peor son 0, 1, 2 y 3. Ese número es pequeño a propósito y es la razón de que la organización por frecuencia de cambio sea obligatoria y no opcional.

La correspondencia con la API es literal: el índice de @group es el primer argumento de setBindGroup, y el de @binding es el campo binding de la entrada correspondiente del bind group layout y del bind group.

pase.setBindGroup(0, grupoCamara);      // @group(0)
pase.setBindGroup(1, grupoEscena);      // @group(1)
pase.setBindGroup(2, grupoMaterial);    // @group(2)

El tipo WGSL decide el tipo de entrada

Cada declaración de recurso implica una clase de entrada en el bind group layout, y la correspondencia es rígida:

La dimensión de la textura en el tipo WGSL —texture_2d, texture_2d_array, texture_cube, texture_3d— tiene que coincidir con el viewDimension de la entrada. Y el parámetro de tipo f32, u32 o i32 tiene que coincidir con el sampleType. Un desajuste no se detecta al compilar el módulo: se detecta al crear el pipeline, y el mensaje es de layout aunque el error esté en el shader.

La regla de unicidad y las vistas alternativas

La regla exacta es más permisiva de lo que parece: dos variables de módulo no pueden tener el mismo par @group y @binding si las dos las usa estáticamente el mismo punto de entrada. Si las usan puntos de entrada distintos, es perfectamente legal.

Eso abre un patrón muy útil: declarar el mismo buffer con dos tipos distintos y usar cada uno donde convenga.

struct Particula {
  posicion : vec4f,
  velocidad : vec4f,
};

// Vista tipada: la usa el shader de simulacion.
@group(0) @binding(0) var<storage, read_write> particulas : array<Particula>;

// Vista cruda del mismo buffer: la usa el shader que lo pone a cero.
@group(0) @binding(0) var<storage, read_write> crudo : array<vec4f>;

@compute @workgroup_size(64)
fn simular(@builtin(global_invocation_id) id : vec3u) {
  particulas[id.x].posicion += particulas[id.x].velocidad;   // solo usa 'particulas'
}

@compute @workgroup_size(64)
fn limpiar(@builtin(global_invocation_id) id : vec3u) {
  crudo[id.x] = vec4f(0.0);                                  // solo usa 'crudo'
}

Los dos puntos de entrada comparten bind group layout, comparten buffer y ven el mismo rango de memoria con dos tipos distintos. Es la forma limpia de tener un shader de inicialización que no necesita conocer la estructura, o de leer un buffer de estructuras como enteros para un radix sort.

Lo que no puedes hacer es usar las dos vistas en el mismo punto de entrada. Si lo intentas, el módulo no compila.

Uso estático y sus consecuencias

Un recurso lo usa estáticamente un punto de entrada cuando aparece en su cuerpo o en el de cualquier función que llame, directa o indirectamente. No importa si la ejecución llega a esa línea: importa que el compilador vea el nombre. Un acceso dentro de un if que siempre es falso cuenta como uso.

De ahí salen tres consecuencias que aparecen a diario:

El layout que exige un pipeline lo determinan los recursos usados estáticamente por sus puntos de entrada, no los declarados en el módulo. Puedes declarar diez recursos y usar tres; el pipeline solo necesita esos tres, aunque el layout puede declarar más.

Comentar una línea cambia el layout. Es el efecto secundario más desconcertante mientras depuras: quitas la textura de una fórmula para ver qué pasa, y de pronto el bind group deja de ser compatible. La solución rápida es una asignación de descarte que mantenga el uso vivo.

_ = textureSampleLevel(albedo, muestreo, vec2f(0.0), 0.0);   // mantiene el uso estatico

Los límites por etapa se cuentan sobre lo declarado en el layout, no sobre lo usado. Un bind group layout con doce uniform buffers visibles desde tres etapas consume presupuesto en las tres, aunque el shader lea uno.