BabylonJS/Babylon.js · error · Error

Depth texture is required for aerial perspective compositor.

Error message

Depth texture is required for aerial perspective compositor.

What it means

The aerial perspective compositor blends atmosphere into already-rendered geometry based on per-pixel depth. It requires a scene depth texture bound via `atmosphere.depthTexture`. Inside the render callback the code re-checks `this.depthTexture === null` and throws because sampling depth is impossible without it.

Source

Thrown at packages/dev/addons/src/atmosphere/atmosphere.ts:1122

        if (
            !effectWrapper.isReady() ||
            !(skyViewLut?.isReady() ?? true) ||
            !multiScatteringLut.isReady() ||
            !transmittanceLut.isReady() ||
            !(aerialPerspectiveLut?.isReady() ?? true) ||
            !this.depthTexture.isReady()
        ) {
            return;
        }

        DrawEffect(
            engine,
            this._effectRenderer!,
            effectWrapper,
            null, // No render target, it will render to the current buffer.
            (effectRenderer, _, effect) => {
                if (this.depthTexture === null) {
                    throw new Error("Depth texture is required for aerial perspective compositor.");
                }
                this.bindUniformBufferToEffect(effect);
                effectRenderer.bindBuffers(effect);
                effect.setTexture("transmittanceLut", transmittanceLut);
                effect.setTexture("multiScatteringLut", multiScatteringLut);
                if (this._isSkyViewLutEnabled) {
                    effect.setTexture("skyViewLut", skyViewLut);
                }
                if (this._isAerialPerspectiveLutEnabled) {
                    effect.setTexture("aerialPerspectiveLut", aerialPerspectiveLut);
                }
                effect.setTexture("depthTexture", this.depthTexture);
                effectRenderer.draw();
            },
            1, // depth to use in the compositor.
            this.applyApproximateTransmittance ? Constants.ALPHA_PREMULTIPLIED_PORTERDUFF : Constants.ALPHA_ONEONE,
            true, // depthTest
            false, // depthWrite

View on GitHub (pinned to 0592b347b8)

Solutions

1. Set a depth texture before rendering: `atmosphere.depthTexture = scene.enableDepthRenderer().getDepthMap().getDepthTexture()` (or pass `options.depthTexture`).
2. If aerial perspective is not wanted, disable the compositor path so depth is never required (use Atmosphere as sky only).
3. Re-assign depthTexture whenever the prepass/depth renderer is recreated (resize, render target rebuild) so it is never null at draw time.

Example fix

// before
const atmosphere = new Atmosphere(scene, [sun]); // depthTexture defaults to null
atmosphere.enableAerialPerspective?.(); // throws
// after
const depthRenderer = scene.enableDepthRenderer();
const atmosphere = new Atmosphere(scene, [sun], { depthTexture: depthRenderer.getDepthMap().getDepthTexture() });

const depthTex = atmosphere.depthTexture ?? scene.enableDepthRenderer().getDepthMap().getDepthTexture();
if (!depthTex) throw new Error("depth texture unavailable");
atmosphere.depthTexture = depthTex;

const hasDepth = (a: Atmosphere): a is Atmosphere & { depthTexture: WebGLTexture | GPUTexture } => a.depthTexture !== null;

try {
  scene.render();
} catch (e) {
  if (String(e).includes("Depth texture is required")) {
    atmosphere.depthTexture = scene.enableDepthRenderer().getDepthMap().getDepthTexture();
  } else throw e;
}

When it happens

Trigger: Enabling aerial perspective (compositor mode) on an Atmosphere instance without setting `atmosphere.depthTexture = ...` (and not passing `options.depthTexture`) before/at render time.

Common situations: Using Atmosphere purely as a skybox (no depth needed) and then enabling the aerial-perspective/post-process path; forgetting to rebind depthTexture after recreating the render target or on scene resize; constructing with options that omit depthTexture.

Related errors

• Atmosphere is not supported on WebGL ${engine.version}.
• Atmosphere only supports one light source currently.
• Sample2DRgbaToRef: widthPx and heightPx must be positive.
• Sample2DRgbaToRef: data length (${data.length}) is less than
• FrameGraphHighlightLayerTask "${this.name}": objectRendererT

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