BabylonJS/Babylon.js · error · Error

HDR prefiltering is not available in WebGL 1., you can use r

Error message

HDR prefiltering is not available in WebGL 1., you can use real time filtering instead.

What it means

HDRFilter's prefilter() generates pre-filtered mip levels for an HDR environment texture so it can be used for IBL. The library throws this when the engine does not support texture prefiltering, which Babylon.js signals via Engine._features.allowTexturePrefiltering (false on WebGL 1 / WebGPU not being used and engine feature unsupported). The message suggests falling back to real-time HDR filtering (HDRFilter without prefiltering) instead.

Source

Thrown at packages/dev/core/src/Materials/Textures/Filtering/hdrFiltering.ts:221

     * @param texture Texture to filter
     * @returns true if the filter is ready
     */
    public isReady(texture: BaseTexture) {
        return texture.isReady() && this._effectWrapper.effect.isReady();
    }

    /**
     * Prefilters a cube texture to have mipmap levels representing roughness values.
     * Prefiltering will be invoked at the end of next rendering pass.
     * This has to be done once the map is loaded, and has not been prefiltered by a third party software.
     * See http://blog.selfshadow.com/publications/s2013-shading-course/karis/s2013_pbs_epic_notes_v2.pdf for more information
     * @param texture Texture to filter
     * @returns Promise called when prefiltering is done
     */
    // eslint-disable-next-line @typescript-eslint/naming-convention
    public async prefilter(texture: BaseTexture): Promise<void> {
        if (!this._engine._features.allowTexturePrefiltering) {
            throw new Error("HDR prefiltering is not available in WebGL 1., you can use real time filtering instead.");
        }

        this._effectRenderer = new EffectRenderer(this._engine);
        this._effectWrapper = this._createEffect(texture);

        await this._effectWrapper.effect.whenCompiledAsync();

        this._prefilterInternal(texture);
        this._effectRenderer.dispose();
        this._effectWrapper.dispose();
    }
}

View on GitHub (pinned to 0592b347b8)

Solutions

1. Create the engine with WebGL 2 (default in recent Babylon versions) and verify engine._features.allowTexturePrefiltering === true before calling prefilter()
2. If WebGL 1 must be supported, do not call prefilter(); use the real-time HDR filtering path (filteringStrength / runtime filtering) so filtering happens per-frame
3. Use a pre-baked .env file (converted via the Babylon sandbox/Ibl baker) instead of runtime prefiltering of an .hdr texture
4. Upgrade Babylon.js / ensure WebGPU engine is used where supported

Example fix

// before
const hdrFilter = new HDRFilter(engine, cubeMapSize);
await hdrFilter.prefilter(hdrTexture);
// after
if (engine._features.allowTexturePrefiltering) {
    const hdrFilter = new HDRFilter(engine, cubeMapSize);
    await hdrFilter.prefilter(hdrTexture);
} else {
    // WebGL 1 fallback: load a pre-baked .env or rely on real-time filtering
    const envTexture = CubeTexture.CreateFromPrefilteredData('environment.env', scene);
}

if (!engine._features.allowTexturePrefiltering) {
    // WebGL 1 or unsupported engine: skip prefiltering, use real-time filtering or .env
    return CubeTexture.CreateFromPrefilteredData('environment.env', scene);
}

function canPrefilter(engine: AbstractEngine): boolean {
    return engine._features.allowTexturePrefiltering === true;
}

try {
    await hdrFilter.prefilter(texture);
} catch (e) {
    if (String(e?.message).includes('HDR prefiltering')) {
        texture = CubeTexture.CreateFromPrefilteredData('environment.env', scene); // fallback
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling hdrFilter.prefilter(texture) on an engine where _features.allowTexturePrefiltering is false — i.e., a WebGL1Engine or a WebGL2 context without the required capabilities that Babylon uses to decide prefiltering support.

Common situations: App runs on WebGL 1 (older browsers/devices, forced WebGL1 fallback); engine created with default options on hardware lacking float texture rendering support; loading .hdr/.env files for PBR on legacy mobile browsers.

Related errors

• HDR prefiltering is not available in WebGL 1., you can use r
• Instanced arrays are required for MSDF text rendering.
• createComputeEffect: This engine does not support compute sh
• createComputePipelineContext: This engine does not support c
• computeDispatch: This engine does not support compute shader

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/b77d2facfdd82b41. Report an issue: GitHub.