El diccionario constants: dar valores al crear el pipeline

Los valores de las override se entregan en un diccionario dentro del descriptor de cada etapa programable. Es una estructura minúscula, con tres reglas de conversión y una particularidad que sorprende: no hay un diccionario por pipeline, hay uno por etapa, y eso significa que el mismo módulo puede compilarse con valores distintos en el vertex y en el fragment del mismo pipeline.

Dónde va

constants es un campo de cada etapa programable: vertex, fragment y compute.

const pipeline = device.createRenderPipeline({
  label: 'pbr con 8 luces y niebla',
  layout: disposicion,
  vertex: {
    module: modulo,
    entryPoint: 'vs',
    buffers: [layoutVertices],
    constants: { ESCALA_MUNDO: 100.0 },
  },
  fragment: {
    module: modulo,
    entryPoint: 'fs',
    targets: [{ format }],
    constants: {
      NUM_LUCES: 8,
      USA_NIEBLA: 1,
      EXPOSICION: 1.2,
    },
  },
  primitive: { topology: 'triangle-list', cullMode: 'back' },
});

Y en un pipeline de cómputo:

const pipelineComputo = device.createComputePipeline({
  layout: disposicion,
  compute: {
    module: modulo,
    entryPoint: 'reducir',
    constants: { TAM_GRUPO: 256 },
  },
});

Las claves

La clave es el @id si la override lo tiene, y el nombre de la variable si no lo tiene. Las claves del diccionario son cadenas, así que un identificador numérico se escribe como número y JavaScript lo convierte:

@id(0) override NUM_LUCES : u32 = 4u;
       override EXPOSICION : f32 = 1.0;

constants: {
  0: 8,              // por @id
  EXPOSICION: 1.2,   // por nombre
}

Dos errores de validación que produce esto:

Una clave que no corresponde a ninguna override hace fallar la creación del pipeline. No se ignora silenciosamente, lo cual es una buena noticia: un nombre mal escrito se detecta.

Una override sin valor por defecto y sin entrada en el diccionario también hace fallar la creación.

La conversión de valores

Todos los valores del diccionario son números de JavaScript, es decir, flotantes de doble precisión, y se convierten al tipo declarado en WGSL:

De ahí salen dos consecuencias prácticas. La primera es que los booleanos se pasan como 0 y 1, y true y false de JavaScript funcionan porque se convierten a esos números. La segunda es que un valor fuera de rango es un error de validación, no un truncamiento: pasar 70000 a un override de tipo f16 falla, igual que pasar 3.5 a uno de tipo u32.

constants: {
  USA_NIEBLA: true,      // funciona: se convierte a 1
  NUM_LUCES: 8,          // bien
  // NUM_LUCES: 8.5,     // ERROR: no es un entero
}

Un diccionario por etapa

Esta es la particularidad que hay que entender bien. Si el vertex shader y el fragment shader salen del mismo módulo y los dos usan la misma override, cada etapa recibe su propio valor.

vertex:   { module: m, entryPoint: 'vs', constants: { CALIDAD: 2 } },
fragment: { module: m, entryPoint: 'fs', constants: { CALIDAD: 0 } },

Eso es legal y compila dos especializaciones distintas del mismo texto. Casi siempre es un bug: alguien cambió la calidad en una etapa y olvidó la otra, y el resultado es un shader donde la geometría se desplaza con una teselación que el sombreado no espera.

La defensa es no escribir el diccionario dos veces:

const cfg = { CALIDAD: 2, USA_NIEBLA: 1, NUM_LUCES: 8 };

const pipeline = device.createRenderPipeline({
  layout: disposicion,
  vertex:   { module: m, entryPoint: 'vs', buffers, constants: cfg },
  fragment: { module: m, entryPoint: 'fs', targets, constants: cfg },
  primitive: { topology: 'triangle-list' },
});

Pasar el mismo objeto a las dos etapas garantiza que no se desincronicen, y no cuesta nada porque las override que una etapa no usa se ignoran sin error.

const pipelines = await Promise.all(
  variantes.map((cfg) => device.createRenderPipelineAsync({ ...descriptor, fragment: { ...frag, constants: cfg } }))
);