Material disposal behavior across Three.js renderer program cache boundaries

Three.js evicts a cached WebGLProgram only after the last material referencing it has been disposed. Eviction is strictly reference-count driven; the renderer does not age out programs or evict them under memory pressure. renderer.info does not expose a reliable public counter for live shader programs in current releases, so developers must inspect internal renderer state to observe program lifetime. The documented compatibility boundary guarantees that material.dispose() releases material-specific GPU resources, but it does not promise immediate deletion of the underlying shader program, particularly when programs are shared across materials.

Program Eviction Conditions

When material.dispose() is called, the renderer decrements the reference count associated with the material's compiled program. If another material with compatible shader parameters and renderer state still references that program, the program remains cached. Only when the final referencing material is disposed does the count reach zero and the renderer become eligible to release the program from GPU memory.

There is no LRU or automatic eviction based on time or memory pressure. A program that was never rendered may not have a compiled program to release, so disposing an unused material is a no-op for the program cache.

renderer.info and Program Visibility

renderer.info.memory tracks geometries and textures, but it does not provide a stable, public counter for live shader programs across recent Three.js releases. Older or experimental properties such as renderer.info.programs are not reliable and may be absent. To count active programs, developers must inspect internal state—for example, the program cache inside WebGLPrograms or a successor manager—or use browser-level WebGL debugging tools. These internals are not part of the public API and can change without notice between minor versions.

Documented Boundary and Context Safety

The documented contract for material.dispose() covers resources owned by the material itself. The release of the underlying WebGLProgram is treated as an implementation detail of the renderer's cache. Three.js does not guarantee synchronous program deletion at the moment of disposal, and browser WebGL implementations may defer actual driver-side deallocation even after gl.deleteProgram is called. Program release occurs without a context loss, but the timing is asynchronous relative to the JavaScript call.

Practical Verification

Because cache internals have been refactored across Three.js versions, verify behavior against your target release rather than assuming stable APIs. A conservative test is to create two materials with identical parameters, render both, dispose one, and confirm the program persists until the second material is disposed. Use a browser GPU profiler or WebGL debug extension to observe actual deletion events after the final dispose(), accounting for driver-side latency.