Debugging and performance
Quick answer
This tutorial shows how to surface silent GPU failures and then reduce cost. It enables the debug, debugShaders and debugFramebuffers Device options, reads shader logs with getCompilationInfoSync and getTranslatedSource, and inspects pipeline linkStatus. It labels commands with pushDebugGroup and reads pixels back through readBuffer plus readAsync. Performance advice covers capped pixel ratios, setNeedsRedraw, shared pipelines and instanced attributes. Readers can diagnose a black frame and find the real bottleneck.
Key points
- Enable debug and debugShaders only in development builds, never in production.
- Read compilation logs with getCompilationInfoSync and check linkStatus before drawing.
- Batch repeated draws with instanceCount and stepMode set to instance.
Example
const device = await luma.luma.createDevice({
type: 'webgl',
adapters: [luma.webgl2Adapter],
createCanvasContext: {
canvas: document.getElementById('cv'),
useDevicePixels: Math.min(window.devicePixelRatio, 2),
autoResize: true
},
debug: true,
debugShaders: 'errors', // 'never' | 'errors' | 'warnings' | 'always'
debugFramebuffers: true, // 把帧缓冲缩略画到画布上
onError: function (error, context) {
console.error(error, context);
}
});const fs = device.createShader({ stage: 'fragment', source: fsSource });
if (fs.compilationStatus === 'error') {
console.log(fs.getCompilationInfoSync());
console.log(fs.getTranslatedSource());
}
const pipeline = device.createRenderPipeline({
vs: vs,
fs: fs,
topology: 'triangle-list',
bufferLayout: [{ name: 'positions', stepMode: 'vertex', format: 'float32x3' }]
});
console.log(pipeline.linkStatus); // 'pending' | 'success' | 'error'
console.log(pipeline.isPending);Notes
- readAsync stalls the GPU pipeline, so never call it inside the frame loop.
- Rebuilding buffers or textures in onRender causes sharp frame drops.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). Debugging and performance. https://www.jingweizhi.com/en/lumagl/tutorials/debugging-perf.html (accessed 2026-11-03).