getContext webgpu: qué es el contexto y qué no es

El contexto de canvas de WebGPU es el objeto más pequeño de la API y el peor entendido. No es un renderizador, no guarda estado gráfico y no dibuja nada: es un intermediario entre tu dispositivo y el compositor del navegador, cuyo único trabajo real es entregarte una textura por fotograma y llevársela cuando terminas. Casi todos los problemas de «no se ve nada» vienen de tratarlo como si fuera algo más.

Un intermediario, no un renderizador

const canvas = document.querySelector('#lienzo');
const context = canvas.getContext('webgpu');

Esa llamada no toca la GPU. Devuelve un objeto que todavía no sirve para nada, porque no sabe con qué dispositivo va a trabajar ni en qué formato. Es deliberado y refleja cómo funciona por dentro: el contexto es el dueño de una cadena de intercambio de imágenes que el compositor del navegador va a leer, y hasta que no sabes qué dispositivo las va a producir no se puede reservar nada.

La secuencia completa de un fotograma, vista desde el sistema, es esta. El compositor del navegador tiene una lista de superficies que combina para producir lo que ves: el texto de la página, las imágenes, los vídeos, y también los canvas acelerados. El contexto de WebGPU gestiona una de esas superficies. Cuando llamas a getCurrentTexture(), el contexto te presta una imagen de su cadena para que escribas en ella. Cuando el fotograma termina, la entrega al compositor, que la combina con el resto de la página según las reglas de CSS y produce la imagen final.

De ahí salen tres hechos que explican mucho comportamiento.

El contexto no dibuja: el dispositivo dibuja. Todo lo que se pinta se pinta con un GPURenderPassEncoder cuyo adjunto de color es una vista de la textura que el contexto prestó. El contexto solo entrega y recoge.

El contexto no tiene bucle. No hay nada equivalente a present() o swapBuffers(). La entrega ocurre sola cuando el navegador va a componer un fotograma. Tu bucle es requestAnimationFrame y nada más.

Un canvas tiene un solo contexto en toda su vida. Si el elemento ya tiene un contexto 2D o de WebGL, getContext('webgpu') devuelve null. Para superponer capas se usan varios elementos canvas apilados con CSS.

Los cuatro métodos

La superficie de la API es minúscula.

configure(configuracion) conecta el contexto con un dispositivo y fija el formato y las opciones de la cadena de imágenes. Sin esto, getCurrentTexture() no funciona. Tiene su propia lección porque el descriptor tiene siete campos y varios importan.

unconfigure() deshace la configuración y libera la cadena de imágenes. Es lo que hay que llamar cuando una vista se desmonta y el canvas va a seguir existiendo, o antes de reconfigurar con un dispositivo distinto tras una pérdida.

getCurrentTexture() devuelve la GPUTexture sobre la que dibujar este fotograma. Es el método que más reglas tiene y merece la lección del ciclo del fotograma.

getConfiguration() devuelve la configuración actual, o null si el contexto no está configurado. Sirve para dos cosas: comprobar si hay que configurar, y detectar qué campos soporta la implementación, porque la especificación indica que un agente de usuario que no implemente una opción no debería exponer ese miembro. Es el mecanismo de detección de características para cosas como el mapeo de tonos.

const conf = context.getConfiguration();
if (conf === null) {
  console.log('el contexto no esta configurado todavia');
} else {
  console.log('formato actual:', conf.format);
  console.log('soporta toneMapping:', 'toneMapping' in conf);
}

Y una propiedad: context.canvas, que devuelve el elemento del que salió. Es útil para no tener que arrastrar la referencia por todas partes.

Por qué el contexto se obtiene antes que el dispositivo

Parece un orden extraño: obtener un objeto inútil y rellenarlo después. Hay tres razones concretas.

El canvas existe en el DOM, no en la GPU. getContext es una operación del elemento HTML, síncrona por definición desde que existe canvas. Hacerla asíncrona para esperar a que hubiera un dispositivo habría roto la coherencia con el resto de la plataforma.

El dispositivo puede cambiar. Tras una pérdida, el canvas sigue siendo el mismo y el dispositivo es otro. Que la asociación se establezca en configure() y no en getContext() permite reconfigurar sin tocar el DOM.

Un dispositivo puede alimentar varios canvas. No hay una relación uno a uno. Una aplicación con cuatro vistas puede tener cuatro canvas, cuatro contextos y un solo dispositivo, compartiendo pipelines y recursos entre las cuatro. Eso solo funciona si la asociación es por configuración y no por creación.

Ese último punto es más útil de lo que parece. Un editor con vista superior, frontal, lateral y en perspectiva no necesita cuatro dispositivos ni cuatro copias de la geometría: necesita cuatro contextos configurados con el mismo dispositivo, y cuatro pases de render en el mismo command buffer.

const device = await adapter.requestDevice();
const formato = navigator.gpu.getPreferredCanvasFormat();

const vistas = ['#sup', '#frente', '#lado', '#persp'].map((sel) => {
  const canvas = document.querySelector(sel);
  const ctx = canvas.getContext('webgpu');
  ctx.configure({ device, format: formato, alphaMode: 'opaque' });
  return { canvas, ctx };
});

// Un solo encoder, cuatro pases, un solo submit.
const encoder = device.createCommandEncoder();
for (const v of vistas) {
  const pase = encoder.beginRenderPass({
    colorAttachments: [{
      view: v.ctx.getCurrentTexture().createView(),
      clearValue: { r: 0.04, g: 0.04, b: 0.06, a: 1 },
      loadOp: 'clear',
      storeOp: 'store',
    }],
  });
  // ... dibujar la escena con la camara de esta vista
  pase.end();
}
device.queue.submit([encoder.finish()]);

Los errores que produce entenderlo mal

Cuatro síntomas frecuentes, todos con la misma raíz.

«getCurrentTexture lanza un error». El contexto no está configurado. Es el fallo más común y su causa habitual es reconfigurar tras una pérdida y olvidarse de que unconfigure deja el contexto inutilizable hasta la siguiente configuración.

«El canvas está negro pero no hay errores». El pase dibujó a una textura que no era la del contexto, o el storeOp era 'discard', o el contexto se configuró con un formato distinto del que declara el pipeline. Ninguna de las tres da error de consola.

«Se ve el fotograma anterior». Se guardó la textura o su vista en una variable y se está reutilizando entre fotogramas. La textura del contexto no es estable entre fotogramas.

«Funciona en un canvas y no en el segundo». El segundo elemento ya tenía un contexto de otro tipo, o no se configuró.

const dpr = Math.min(window.devicePixelRatio || 1, 2);
const rect = canvas.getBoundingClientRect();
canvas.width  = Math.max(1, Math.round(rect.width  * dpr));
canvas.height = Math.max(1, Math.round(rect.height * dpr));

Con el intermediario en su sitio, toca el descriptor que lo pone a funcionar: configure() completo.