Inspeccionar un frame: Spector.js y el Inspector de Three.js

Cuando el diagnóstico dice “limitado por GPU” y ya has bajado la resolución, hace falta ver qué está dibujando realmente el motor. Un capturador de frames intercepta todas las llamadas a la API gráfica durante un fotograma y te devuelve la lista completa, con su estado, sus texturas y su resultado visual paso a paso. Es la única herramienta que responde preguntas del tipo “¿por qué hay ochocientos draw calls si solo tengo doscientos objetos?” o “¿esta textura está subida como RGBA de 32 bits?”.

Spector.js

Spector.js es un capturador de frames para WebGL, disponible como extensión de navegador y como biblioteca embebible. Su modelo es simple: se coloca entre tu código y el contexto de WebGL, registra todas las llamadas de un frame, y presenta el resultado en un visor.

<script src="https://spectorcdn.babylonjs.com/spector.bundle.js"></script>
<script>
	const spector = new SPECTOR.Spector();
	spector.displayUI();
</script>

Con displayUI() aparece una barra flotante con un botón de captura. También se puede disparar por código, que es más práctico cuando el frame problemático solo ocurre en un momento concreto:

const spector = new SPECTOR.Spector();

spector.onCapture.add( ( resultado ) => {

	// El resultado es un objeto JSON con todo el frame.
	console.log( resultado );

} );

// Capturar el proximo frame de este canvas.
document.addEventListener( 'keydown', ( e ) => {

	if ( e.key === 'c' ) spector.captureCanvas( renderer.domElement );

} );

La captura es cara —intercepta y serializa cada llamada— así que el frame capturado tarda muchísimo más de lo normal. Eso es esperado y no invalida nada: Spector no mide tiempos, describe qué se hace.

Qué leer en la captura

El visor muestra la lista de comandos agrupada por pasadas de dibujo, y cada comando lleva el estado completo en ese instante. Estas son las cinco preguntas que responde y que ninguna otra herramienta contesta con la misma precisión.

¿Cuántos draw calls hay de verdad, y de dónde salen? renderer.info te da el número; Spector te dice cuáles. Es donde descubres que el mapa de sombras dibuja la escena entera otra vez, que el post-proceso tiene siete pases en lugar de tres, o que un EffectComposer está copiando entre render targets más veces de las necesarias.

¿Qué se está redibujando encima de qué? Cada draw call muestra una miniatura del framebuffer después de ejecutarse. Recorriendo la secuencia se ve el overdraw literalmente: si la misma zona de pantalla se repinta ocho veces, ahí está tu problema de fragmentos.

¿Cómo están configuradas las texturas? Cada textura muestra su formato, tamaño, mipmaps, filtrado y wrapping. Es la forma más rápida de encontrar una textura de 4096 por 4096 sin comprimir consumiendo 64 MB por sí sola, o una que debería estar en sRGB y está en lineal, o una que se ha subido sin mipmaps y por eso brilla al alejarse.

¿Cuántos cambios de estado hay? Cada useProgram, bindTexture, bindBuffer y enable aparece. Un número desproporcionado de cambios de programa entre draw calls indica que los objetos no están ordenados por material, lo que es un coste de CPU y de driver que no aparece en ningún contador de Three.js.

¿Qué contiene exactamente este uniform? Con el valor de cada uniform en cada draw call se resuelven en minutos los bugs de “no se ve nada”: una matriz mal construida, una luz con intensidad cero, un opacity que quedó a cero de una animación anterior.

Spector es solo para WebGL. No funciona con WebGPU, ni con el WebGPURenderer cuando este ha caído a su backend de WebGL, porque la instrumentación se hace sobre el contexto y hay que activarla antes de crearlo. Para WebGPU, las herramientas de captura equivalentes son las que traen los navegadores en sus canales de desarrollo, todavía menos maduras.

El Inspector de Three.js

La r184 trae un inspector propio en los addons, pensado para WebGPURenderer y con una capacidad que Spector no tiene: medir tiempo de GPU por pase.

import * as THREE from 'three/webgpu';
import { Inspector } from 'three/addons/inspector/Inspector.js';

const renderer = new THREE.WebGPURenderer( { antialias: true } );
renderer.inspector = new Inspector();

document.body.appendChild( renderer.domElement );
await renderer.init();

Con esas dos líneas aparece un panel acoplado al canvas con varias pestañas: rendimiento, memoria, parámetros, consola, línea de tiempo y ajustes. Lo que hace por debajo es lo interesante: al asignarlo, el inspector activa renderer.backend.trackTimestamp y comprueba si el dispositivo soporta timestamp-query; si no lo soporta, lo dice explícitamente en su consola en lugar de mostrar ceros silenciosamente.

La pestaña de rendimiento separa, por cada pase, el tiempo de CPU y el de GPU, y calcula además un residuo llamado miscellaneous que es la diferencia entre la duración real del frame y la suma de lo medido. Ese residuo es información valiosa por sí misma: si es grande, hay trabajo que no está pasando por el renderer, que suele ser tu lógica o el navegador.

La pestaña de memoria muestra los contadores de info.memory con sus tamaños en bytes, que como viste es la información que WebGL no da.

Y hay dos integraciones con TSL que merece la pena conocer. renderer.inspector.createParameters( nombre ) devuelve un grupo donde exponer uniforms con controles, sin necesidad de traer una biblioteca de interfaz aparte:

const gui = renderer.inspector.createParameters( 'Simulacion' );

gui.add( gravedad, 'value', - 0.02, 0, 0.0001 ).name( 'gravedad' );
gui.add( rebote, 'value', 0.1, 1, 0.01 ).name( 'rebote' );

Y .toInspector( nombre ) sobre un nodo de TSL lo hace visible como salida intermedia en el visor, que es la forma más directa de depurar un grafo de shading: puedes ver el resultado de un paso concreto de tu cadena de post-proceso sin desmontar nada.

const escena = pass( scene, camera ).toInspector( 'Escena' );
const desenfocada = gaussianBlur( escena.getTextureNode() ).toInspector( 'Desenfoque' );

Qué herramienta para qué pregunta