WebGPU in WebXR

Babylon.js can render immersive WebXR sessions with a WebGPU engine through the browser's experimental XRGPUBinding implementation.

Check the three levels of support

WebGPU, immersive WebXR, and WebGPU-XR are separate capabilities:

• WebGPUEngine.IsSupportedAsync checks whether Babylon can create a WebGPU engine.
• WebXRSessionManager.IsSessionSupportedAsync("immersive-vr") checks whether the browser reports support for that immersive WebXR session mode.
• WebXRSessionManager.IsWebGPUXRSupported checks whether the runtime exposes the XRGPUBinding projection-layer methods and the XRGPUSubImage.getViewDescriptor method required by Babylon.

IsWebGPUXRSupported is an experimental, static boolean getter. It requires the XRGPUSubImage interface and XRGPUSubImage.prototype.getViewDescriptor because Babylon uses that method to create texture views for each projection sub-image. This remains an advisory API-shape check, not a guarantee that the active device, GPU adapter, permissions, and session will work together. The actual session request can still reject.

Select the engine before creating the scene

A WebGPU engine intended for XR must request an XR-compatible adapter when it is created:

import { WebGPUEngine } from "@babylonjs/core/Engines/webgpuEngine";
const engine = new WebGPUEngine(canvas, { xrCompatible: true });
await engine.initAsync();

WebGPU has no equivalent to making an existing context XR-compatible later. If your application supports WebGL fallback, select the rendering backend before creating the scene or any GPU resources:

import { Engine } from "@babylonjs/core/Engines/engine";
import { WebGPUEngine } from "@babylonjs/core/Engines/webgpuEngine";
import { Scene } from "@babylonjs/core/scene";
import { WebXRSessionManager } from "@babylonjs/core/XR/webXRSessionManager";
async function createEngineForImmersiveXR(canvas) {
    const webGPUSupported = await WebGPUEngine.IsSupportedAsync;
    const immersiveXRSupported = await WebXRSessionManager.IsSessionSupportedAsync("immersive-vr");
    // Includes XRGPUBinding projection APIs and XRGPUSubImage.getViewDescriptor.
    const webGPUXRSupported = WebXRSessionManager.IsWebGPUXRSupported;
    if (webGPUSupported && immersiveXRSupported && webGPUXRSupported) {
        const engine = new WebGPUEngine(canvas, { xrCompatible: true });
        try {
            await engine.initAsync();
            return engine;
        }
        catch (error) {
            engine.dispose();
            console.warn("Could not initialize an XR-compatible WebGPU engine; using WebGL instead.", error);
        }
    }
    return new Engine(canvas, true);
}
const engine = await createEngineForImmersiveXR(canvas);
const scene = new Scene(engine);

Babylon.js never swaps an existing WebGPU engine or scene to WebGL. If WebGPU session negotiation later fails, falling back requires reloading or fully rebuilding the engine, scene, and all GPU resources with a WebGL engine.

Enable WebXR Layers before entering XR

WebGPU-XR uses an XRProjectionLayer, so the WebXR Layers feature is required. Enable it before calling enterXRAsync:

import { WebXRFeatureName } from "@babylonjs/core/XR/webXRFeaturesManager";
const xr = await scene.createDefaultXRExperienceAsync();
const featuresManager = xr.baseExperience.featuresManager;
featuresManager.enableFeature(WebXRFeatureName.LAYERS, "stable");
try {
    await xr.baseExperience.enterXRAsync("immersive-vr", "local-floor");
}
catch (error) {
    // Show the error and offer to reload or rebuild the application with WebGL.
    console.error("Could not start the XR session:", error);
}

When using ES modules with tree shaking, import the Layers feature so it is registered:

import "@babylonjs/core/XR/features/WebXRLayers.js";

Babylon rejects WebGPU XR entry with actionable guidance when the required XRGPUBinding projection path or XRGPUSubImage.getViewDescriptor support is missing, or when Layers was not enabled. If the browser rejects the WebGPU session request with NotSupportedError, Babylon preserves the original error as the cause and reports that the application must recreate the scene with WebGL to fall back.

Current feature caveats

• Projection layers and sub-image view descriptors are required. The runtime must expose XRGPUSubImage.prototype.getViewDescriptor; the WebGL XRWebGLLayer rendering path is not available to a WebGPU engine.
• Multiview is not available with WebGPU-XR yet. preferMultiviewOnInit does not enable it on this path.
• Raw Camera Access is unavailable. The browser exposes camera images through XRWebGLBinding, not XRGPUBinding.
• Space Warp is unavailable. Its current implementation depends on WebGL-specific binding functionality.
• Additional graphics layers are method-gated. Quad, cylinder, equirectangular, and cube layers require the matching XRGPUBinding.create*Layer factory and getSubImage. Babylon warns and returns null when either requirement is missing, unless an enabled mesh fallback was requested.
• Depth Sensing requires CPU-optimized depth. Request CPU usage with usagePreference: ["cpu"]; GPU-optimized environment depth has no XRGPUBinding equivalent.

These limitations are specific to the experimental WebGPU-XR path. A feature may still be available in a WebGL-backed WebXR session.

Further reading

WebXR

Learn about creating immersive VR and AR web experiences with WebXR in Babylon.js.

WebXR Session Manager

Learn all about the WebXR session manager in Babylon.js.

WebXR Layers

Create and manage projection, quad, cylinder, equirectangular, cube, and media layers in Babylon.js WebXR experiences.