Skip to content

Fix a black or frozen canvas ​

If nothing renders, or an animation is stuck on one frame, work through this list. The two halves are different problems: a black canvas draws the wrong thing (or nothing), a frozen canvas draws once and never again.

Black canvas ​

The canvas has width / height attributes ​

Radiance only auto-sizes a canvas whose attributes are unset. With them present, the drawing buffer keeps whatever size they say.

html
<!-- ❌ Radiance will not touch these -->
<canvas id="glCanvas" width="800" height="600"></canvas>

<!-- ✅ CSS decides the size -->
<canvas id="glCanvas"></canvas>

See Handle resize and device pixel ratio.

The layout size is zero ​

A width: 100% canvas inside a zero-height parent has no pixels to fill. The drawing buffer stays 0×0 and every draw is a no-op. Give the canvas (or its parent) an explicit size or aspect-ratio, and check canvas.width in the console.

The shader failed to compile ​

Radiance logs could not compile shader: …, and the pass then fails to initialize: glCanvas, renderPass and friends throw could not initialize the render pass, so nothing is ever drawn. Check the console — the log has the GLSL details. See Debug shader compilation errors.

The fragment shader draws black ​

Very easy to achieve on purpose or by accident: a mask that multiplies everything by 0, an unlit vec3(0.), a UV used before it is computed. Replace main() with gl_FragColor = vec4(1., 0., 1., 1.); — if the canvas turns magenta, the pipeline is fine and the maths is not.

A texture never arrived ​

A promise uniform that never settles is simply never uploaded, and the shader samples an unbound texture (black). Usual causes: a wrong URL (check the network tab), CORS on a cross-origin image, or a video that cannot autoplay. loadTexture throws on a failed fetch; loadVideoTexture logs Failed to load texture: …. See Sample images, videos and data.

WebGL2 is unavailable ​

glContext throws No WebGL2 context available. when getContext("webgl2") returns null — headless browsers, old devices, blocklisted GPUs. The throw is uncaught and stops your module: another case where the console says more than the canvas.

Frozen canvas ​

renderMode: "manual" without a render() call ​

Nothing is scheduled in manual mode. Call render() after every change, or switch to "auto". See Choose when to render.

immediate: false and no play() ​

The clock starts paused and uTime never advances. Call play() when you want the animation to start.

A time uniform that lost its name ​

Render mode is inferred from uniform names: a function uniform with time in its name starts the clock. Rename uTime to uClock and the inference falls back to auto — the canvas renders on updates only, and an animation with nothing to update stays put. Pass renderMode: "continuous" explicitly.

A uniform assigned in place ​

ts
uniforms.uOffset[0] = 1; // ❌ mutates an array, the proxy never sees it
uniforms.uOffset = [1, 0]; // ✅ top-level assignment schedules a render

See Update uniforms at runtime.

A video texture in manual mode ​

Video frames schedule their own renders — in auto and continuous modes. In manual mode nothing is scheduled, so call render() yourself (from a loop, for example) or leave the mode alone.

The tab was hidden and the clock paused ​

If you call pauseAllLoops() on visibilitychange, remember to call playAllLoops() again. time (unlike elapsedTime) does not jump on resume — see Choose when to render.

Still stuck? ​

Reduce to the smallest thing that can work: one full-screen shader, no uniforms, gl_FragColor = vec4(vUv, 0., 1.). If that draws, re-add pieces one at a time. Getting Started is that minimal case.

See also ​

Released under the MIT License.