queue.writeBuffer: la escritura de cada fotograma

queue.writeBuffer es la función que más se llama en una aplicación de WebGPU y la que más fácil es usar mal, porque su firma tiene cinco parámetros de los que tres son opcionales y dos cambian de unidad según el tipo del argumento que le pases. Detrás hace algo más complejo de lo que aparenta, y saber qué es determina cuándo conviene usarla y cuándo hay algo mejor.

La firma y su trampa

device.queue.writeBuffer(buffer, bufferOffset, data, dataOffset, size);

buffer tiene que tener COPY_DST en su usage. Sin él, error de validación.

bufferOffset es el desplazamiento en el búfer de destino, siempre en bytes, y tiene que ser múltiplo de 4.

data puede ser un ArrayBuffer o cualquier vista tipada.

dataOffset y size son opcionales, y aquí está la trampa: si data es una vista tipada, se miden en elementos; si es un ArrayBuffer, en bytes.

const datos = new Float32Array(1000);

// Escribe los elementos 100 a 199 de 'datos' al principio del buffer.
// dataOffset y size en ELEMENTOS porque datos es un Float32Array.
device.queue.writeBuffer(buffer, 0, datos, 100, 100);   // 400 bytes escritos

// Lo mismo con un ArrayBuffer: ahora los numeros son BYTES.
device.queue.writeBuffer(buffer, 0, datos.buffer, 400, 400);

Las dos líneas escriben lo mismo con números distintos. Es una fuente de errores constante, y la forma de no caer en ella es fijar una convención en tu proyecto y no mezclarlas. La recomendación práctica: usa siempre vistas tipadas y piensa en elementos, que es lo que la mayoría del código de ejemplo hace.

Y una regla de validación adicional: el tamaño escrito, convertido a bytes, tiene que ser múltiplo de 4. Escribir tres bytes lanza un OperationError.

Qué ocurre por debajo

writeBuffer retorna inmediatamente y la escritura no ha ocurrido todavía. Lo que hace la implementación es, en esencia, esto:

Copia tus datos a un búfer de staging interno que gestiona ella. Esa copia sí es síncrona: cuando writeBuffer retorna, puedes modificar tu Float32Array sin que afecte a lo que se va a escribir. Es una garantía importante y es la razón de que writeBuffer sea cómoda.

Encola una operación de copia del staging al búfer de destino, en el mismo orden de la cola que los submit. Eso significa que una escritura hecha antes de un submit es visible para los comandos de ese submit, y una hecha después no lo es para los comandos ya enviados. El orden que ves en tu código es el orden que se respeta.

Recicla el staging interno cuando la copia ha terminado. Ese reciclaje es lo que hace que llamar a writeBuffer mil veces por fotograma no reserve mil búferes, y también es lo que puede saturarse si escribes cantidades muy grandes.

De ese modelo salen dos consecuencias operativas. La primera: writeBuffer es la forma correcta de actualizar datos pequeños cada fotograma, y la implementación está optimizada para ese caso. La segunda: hay una copia extra respecto a escribir en un búfer mapeado, y con volúmenes grandes esa copia se nota.

Los patrones que funcionan

Uniformes por fotograma. El caso más común. Un Float32Array reutilizado, rellenado en sitio, escrito de una vez:

const datosUniformes = new Float32Array(32);   // 128 bytes

function frame() {
  datosUniformes.set(matrizVistaProyeccion, 0);
  datosUniformes.set(posicionCamara, 16);
  datosUniformes[19] = tiempo;
  device.queue.writeBuffer(bufferUniformes, 0, datosUniformes);
  // ... grabar y enviar comandos
}

Reutilizar el mismo array evita reservas y presión sobre el recolector de basura. Una escritura de 128 bytes por fotograma es despreciable.

Actualización parcial. Solo lo que cambió, en lugar del búfer entero:

// Actualizar solo la instancia 42, sin tocar las otras mil.
const OFFSET_INSTANCIA = 42 * 64;
device.queue.writeBuffer(instancias, OFFSET_INSTANCIA, matriz);

Agrupar en lugar de fragmentar. Mil llamadas de 64 bytes cuestan mucho más que una de 64000. Si vas a actualizar muchos elementos, monta un array en JavaScript y escribe una vez.

Cuándo dejar de usarla

Tres casos en que hay algo mejor.

Datos muy grandes que se escriben una vez. Para varios megabytes de geometría al cargar, mappedAtCreation evita la copia intermedia. La diferencia con 200 MB es medible.

Escrituras grandes y repetidas. Si escribes decenas de megabytes por fotograma, el staging interno puede convertirse en el cuello. Un anillo de búferes de staging propios con MAP_WRITE | COPY_SRC da control sobre cuánta memoria se usa y cuándo:

// Anillo propio de staging para escrituras grandes y frecuentes.
const staging = buffersDisponibles.pop() ?? device.createBuffer({
  size: TAM, usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC,
});
await staging.mapAsync(GPUMapMode.WRITE);
new Float32Array(staging.getMappedRange()).set(datosGrandes);
staging.unmap();

const encoder = device.createCommandEncoder();
encoder.copyBufferToBuffer(staging, 0, destino, 0, TAM);
device.queue.submit([encoder.finish()]);
device.queue.onSubmittedWorkDone().then(() => buffersDisponibles.push(staging));

Es bastante más código y solo compensa cuando el perfil dice que compensa.

Datos que ya están en la GPU. Si el contenido que quieres poner en un búfer lo produjo otro búfer, copyBufferToBuffer lo mueve sin pasar por la CPU. Es la operación más rápida de todas y la que se olvida:

const encoder = device.createCommandEncoder();
encoder.copyBufferToBuffer(origen, 0, destino, 0, tamano);
// O la forma corta, equivalente a los desplazamientos a cero:
encoder.copyBufferToBuffer(origen, destino, tamano);
device.queue.submit([encoder.finish()]);

La especificación admite las dos formas. Los desplazamientos y el tamaño tienen que ser múltiplos de 4, el origen necesita COPY_SRC, el destino COPY_DST, y no pueden ser el mismo búfer.

Falta poner nombre a lo que hay detrás de todo esto: el modelo de memoria.