WebXR Composition Layers — High-Performance Rendering

WebXR Hand Tracking — Von Gelenken zu Gesten

Ein praxisnaher Deep-Dive in die WebXR Hand Tracking API — Gelenkpositionen, Pinch-Erkennung, benutzerdefinierte Gestenerkennung und Interaktionsmuster für immersive VR-Anwendungen.

WebXR Hand Tracking — From Joints to Gestures

A practical deep-dive into the WebXR Hand Tracking API — joint positions, pinch detection, custom gesture recognition, and interaction patterns for immersive VR applications.

Das Standard-WebXR-Rendering funktioniert so, dass alles in einen WebGL-Framebuffer gezeichnet wird, den die Runtime anschließend auf das Headset-Display kopiert. Das funktioniert zwar, ist aber für viele gängige Anwendungsfälle ineffizient – insbesondere bei Videos, 2D-UIs und Hintergrundumgebungen.

WebXR Composition Layers ermöglichen es, den App-Framebuffer für bestimmte Inhalte zu umgehen und diese direkt an den GPU-Compositor zu übergeben. Das Ergebnis: geringerer Stromverbrauch, höhere Bildwiederholraten und eine bessere visuelle Qualität für überlagerte Inhalte.

Warum Layer?

Layer spielen ihre Stärken aus bei:

• Video — 180°/360°-Videos, 2D-Videopanels, Video-Call-Feeds
• 2D-UI — Dashboards, Menüs, Benachrichtigungen (einmal rendern, in jedem Frame anzeigen)
• Hintergründe — 360°-Fotos, Environment Maps, Skyboxes
• Passthrough — In AR-Modi werden Layer über die reale Welt gelegt

Der Kompromiss: Sie können keine pro-Pixel Three.js-Effekte auf Layer-Inhalte anwenden. Layer sind für Inhalte gedacht, die keine Shader-Verarbeitung auf App-Ebene benötigen.

Layer-Typen

WebXR definiert vier Layer-Typen, die jeweils einem anderen Zweck dienen:

XRProjectionLayer

Dies ist der Standard-Layer – derjenige, der den herkömmlichen WebGL-Framebuffer ersetzt. Erstellen Sie ihn während des Session-Setups:

const glBinding = new XRWebGLBinding(session, gl);
const projectionLayer = glBinding.createProjectionLayer({
  textureType: "texture", // 'texture' or 'texture-array'
  colorFormat: gl.RGBA8,
  depthFormat: gl.DEPTH_COMPONENT24,
  scaleFactor: 1.0, // Resolution scale (0.5 = half res)
});
session.updateRenderState({
  layers: [projectionLayer], // Must always be the first layer
});

Die Eigenschaft scaleFactor ist entscheidend für die Performance:

• 1.0 = volle Geräteauflösung
• 0.75 = gute Balance auf der Quest 3
• 0.5 = Performance-Modus für komplexe Szenen

XRQuadLayer

Eine flache, rechteckige Oberfläche, die im 3D-Raum positioniert wird. Perfekt für 2D-Inhalte:

const quadLayer = glBinding.createQuadLayer({
  space: referenceSpace,
  layout: "mono",
  width: 2, // meters
  height: 1.5, // meters
  pixelWidth: 1024,
  pixelHeight: 768,
  blendTextureSourceAlpha: true,
});

// Position the quad
quadLayer.transform = new XRRigidTransform({
  x: 0,
  y: 1.5,
  z: -2, // 2m in front, 1.5m up
});

session.updateRenderState({
  layers: [projectionLayer, quadLayer],
});

Anwendungsfälle: 2D-Dashboards in VR, Video-Player-UI, Datenvisualisierungs-Panels.

XRCylinderLayer

Eine gekrümmte Displayfläche, nützlich für immersive Dashboards und Menüs:

const cylinderLayer = glBinding.createCylinderLayer({
  space: referenceSpace,
  layout: "stereo-left-right",
  radius: 3, // meters
  centralAngle: Math.PI * 0.5, // 90 degree arc
  aspectRatio: 1.5, // height = radius * aspect
  pixelWidth: 2048,
  pixelHeight: 2048,
});

Anwendungsfälle: Auto-Dashboards, Cockpit-UIs, Panorama-Menüs, Monitorwände.

XREquirectangularLayer

Ein sphärischer (360°) Layer für Umgebungshintergründe und 360°-Medien:

const equiLayer = glBinding.createEquirectangularLayer({
  space: referenceSpace,
  layout: "stereo-left-right",
  centralAngle: Math.PI * 2, // Full sphere
  radius: 0,
  pixelWidth: 4096,
  pixelHeight: 2048,
});

Anwendungsfälle: 360°-Fotos als Umgebungen, 360°-Videohintergründe, Skyboxes.

Compositing von Layern

Layer werden in der Reihenfolge von hinten nach vorne (back-to-front) basierend auf ihrer Position im Array zusammengesetzt:

// Hintergrundebene (equirektangular)
// ↓ dahinter komponiert
// Quad-Ebene (Dashboard)
// ↓ dahinter komponiert
// Projektionsebene (Haupt-3D-Szene)
session.updateRenderState({
  layers: [projectionLayer, quadLayer, equiLayer],
});

Wait — this is actually front-to-back in the array order. The first layer is rendered first (closest to the viewer). The runtime composits them in the natural over-draw order: layers later in the array appear on top of earlier ones.

Important: Not all runtimes support more than 2-3 simultaneous layers. Check session.supportedLayers to determine the maximum.

Video Playback with XRMediaBinding

Video is where composition layers truly shine. Instead of decoding video to a canvas and uploading to a WebGL texture each frame, XRMediaBinding hands the video decoder output directly to the compositor.

Setup

const mediaBinding = new XRMediaBinding(session);

// Erstellen eines versteckten Video-Elements
const video = document.createElement("video");
video.src = "/videos/my-360-video.mp4";
video.loop = true;
video.muted = true; // Erforderlich für Autoplay-Richtlinien
video.crossOrigin = "anonymous";
await video.play();

// Erstellen einer an das Video gebundenen Quad-Ebene
const videoLayer = mediaBinding.createQuadLayer(video, {
  space: referenceSpace,
  layout: "mono",
  width: 4,
  height: 2.25, // 16:9 Seitenverhältnis
  invertStereo: false,
});

// Positionieren des Videobildschirms
videoLayer.transform = new XRRigidTransform({
  x: 0,
  y: 1.5,
  z: -3,
  y: 0,
  z: 0,
  w: 1, // Quaternion (zum Betrachter ausgerichtet)
});

session.updateRenderState({
  layers: [projectionLayer, videoLayer],
});

360° Video

For 360° video, use an equirectangular layer instead:

const videoLayer = mediaBinding.createEquirectangularLayer(video, {
  space: referenceSpace,
  layout: "stereo-left-right", // Die meisten 360°-Videos sind stereoskopisch
  centralAngle: Math.PI * 2,
  radius: 0,
  pixelWidth: 3840,
  pixelHeight: 1920,
});

Playback Controls in VR

Since the video element lives in the DOM, you can control it programmatically:

// Wiedergabe/Pause via Geste
function togglePlayback() {
  if (video.paused) {
    video.play();
  } else {
    video.pause();
  }
}

// Lautstärkeregelung
function setVolume(level: number) {
  video.volume = Math.max(0, Math.min(1, level));
}

The video layer automatically reflects changes to playback state, volume, and looping.

Performance Benefits

Compared to canvas-based video rendering:

Drawing Content to Layers

For non-video content, you need to render to the layer's color texture:

// In jedem Frame das Sub-Image der Ebene abrufen
const layer = quadLayer;
const subImage = glBinding.getSubImage(layer, frame, eye);

// Color-Texture binden
gl.bindTexture(gl.TEXTURE_2D, subImage.colorTexture);

// Depth/Stencil-Texture binden (optional)
gl.bindTexture(gl.TEXTURE_2D, subImage.depthStencilTexture);

// Inhalte in das Sub-Image rendern
gl.viewport(0, 0, subImage.viewport.width, subImage.viewport.height);
// ... draw calls ...

For quad layers, you typically render a fullscreen quad. For cylinder layers, you render a warped projection. For equirectangular, you render a panoramic image.

Fallback Strategy

Not all browsers or devices support composition layers. Always implement a fallback:

function createLayers(session: XRSession, gl: WebGL2RenderingContext) {
  if (session.supportedLayers?.length > 1) {
    // Use composition layers
    return createCompositionLayers(session, gl);
  } else {
    // Fall back to standard WebGL rendering
    session.updateRenderState({
      baseLayer: new XRWebGLLayer(session, gl),
    });
  }
}

Performance Tuning

• Layer count: Keep it minimal. Each layer adds GPU composition pass overhead.
• Texture resolution: Match pixel dimensions to what the content needs. A 4K video doesn't need an 8K quad layer.
• Blend modes: Use alpha-blend for transparent layers, opaque for solid content.
• Fixed foveated rendering (FFR): Available on some devices. Sets lower resolution in peripheral vision:

session.updateRenderState({
  layers: [projectionLayer],
  foveationLevel: 0.5, // 0.0 = no foveation, 1.0 = max
});

• Layer-Updates: Aktualisieren Sie Layer-Transformationen nicht in jedem Frame, es sei denn, es ist unbedingt erforderlich. Statische Layer können einmalig gesetzt und dann beibehalten werden.

Querverweise der Serie

• Building a WebXR App with Three.js — Integration von Layern in Ihre Anwendung
• WebXR Anchors & Plane Detection — Verankerung von Layern im World Space

Referenzen

• WebXR Composition Layers Spec (W3C)
• MDN: XRCompositionLayer
• Meta Quest: Layer Performance