XRLayer — Schnittstelle · JavaScript-Referenz

Signatur

interface XRLayer extends EventTarget

Beschreibung

XRLayer ist die gemeinsame Basisklasse aller Schichten (Layers), die eine WebXR-Sitzung (XRSession) zur Darstellung an das XR-Gerät übergibt. Die Schnittstelle erbt von EventTarget, definiert aber keine eigenen Eigenschaften oder Methoden. Sie dient als gemeinsamer Typ, damit Schichten unterschiedlicher Art einheitlich behandelt werden können, z. B. im Array layers von XRSession.updateRenderState().

Konkrete Unterklassen sind:

XRWebGLLayer: die klassische WebGL-Schicht aus der Kernspezifikation, gesetzt über baseLayer.
XRCompositionLayer aus dem WebXR Layers Module mit den Unterklassen XRProjectionLayer, XRQuadLayer, XRCylinderLayer, XREquirectLayer und XRCubeLayer.

Direkt instanziieren kann man XRLayer nicht. Schichten entstehen entweder über new XRWebGLLayer(session, gl) oder über die Fabrikmethoden von XRWebGLBinding und XRMediaBinding. Im Code taucht XRLayer deshalb vor allem bei Typprüfungen (instanceof), bei der Feature-Erkennung und als Typangabe auf.

Die API ist nur in sicheren Kontexten (HTTPS) verfügbar. Außerdem muss die Sitzung mit den passenden Features angefordert werden, für Composition Layers zum Beispiel mit requiredFeatures: ["layers"].

Rückgabewert

Typ

XRLayer

Beschreibung

Kein eigener Rückgabewert. Instanzen erhält man nur als Objekte der Unterklassen, z. B. XRWebGLLayer oder XRProjectionLayer.

Beispiele

Feature-Erkennung und Typprüfung

// Prüfen, ob WebXR-Schichten unterstützt werden
const hatXRLayer = 'XRLayer' in window;
const hatLayersModul = 'XRCompositionLayer' in window;
console.log({ hatXRLayer, hatLayersModul });

// Direkte Instanziierung ist nicht erlaubt
try {
  new XRLayer();
} catch (err) {
  console.log(err.name); // TypeError: Illegal constructor
}

{ hatXRLayer: true, hatLayersModul: true } TypeError

XRWebGLLayer als Basisschicht erzeugen (Instanziierung einer Unterklasse)

const startXR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-vr'))) {
    console.log('immersive-vr nicht verfügbar');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-vr');
  const canvas = document.createElement('canvas');
  const gl = canvas.getContext('webgl2', { xrCompatible: true });

  const layer = new XRWebGLLayer(session, gl);
  console.log(layer instanceof XRLayer);     // true
  console.log(layer instanceof EventTarget); // true

  await session.updateRenderState({ baseLayer: layer });
};

document.querySelector('#vr-button').addEventListener('click', startXR);

true true

Projektions- und Quad-Schicht mit dem Layers Module kombinieren

const startMitLayers = async () => {
  const session = await navigator.xr.requestSession('immersive-vr', {
    requiredFeatures: ['layers']
  });
  const gl = document.createElement('canvas')
    .getContext('webgl2', { xrCompatible: true });
  const refSpace = await session.requestReferenceSpace('local');

  const binding = new XRWebGLBinding(session, gl);
  const projection = binding.createProjectionLayer({ textureType: 'texture' });
  const quad = binding.createQuadLayer({
    space: refSpace,
    viewPixelWidth: 1024,
    viewPixelHeight: 512,
    width: 1.0,
    height: 0.5,
    transform: new XRRigidTransform({ z: -2 })
  });

  // Alle Einträge sind XRLayer-Instanzen, Reihenfolge = Zeichenreihenfolge
  const layers = [projection, quad];
  console.log(layers.every((l) => l instanceof XRLayer)); // true

  await session.updateRenderState({ layers });
};

true

// Wichtig · Fallstricke

Nicht direkt konstruierbar: new XRLayer() wirft einen TypeError. Verwenden Sie stattdessen XRWebGLLayer oder die Fabrikmethoden von XRWebGLBinding bzw. XRMediaBinding.
baseLayer und layers schließen sich gegenseitig aus: Wer in updateRenderState() beide Optionen gleichzeitig setzt, bekommt einen NotSupportedError. Das Array layers funktioniert nur, wenn die Sitzung mit dem Feature "layers" angefordert wurde.
Sitzungsbindung: Jede Schicht gehört zu genau der Sitzung, mit der sie erzeugt wurde. Nach session.end() ist sie unbrauchbar und muss für eine neue Sitzung neu erzeugt werden.
Kompatibilität: Nur in sicheren Kontexten (HTTPS) verfügbar. Unterstützt wird die API vor allem von Chromium-basierten Browsern und dem Meta Quest Browser. Firefox und Safari (Desktop) unterstützen WebXR nicht; visionOS Safari unterstützt WebXR nur eingeschränkt. Das Layers Module ist noch weniger verbreitet, daher vorher mit 'XRCompositionLayer' in window prüfen.
Das WebGL-Kontextobjekt muss XR-kompatibel sein, also mit xrCompatible: true erzeugt oder per gl.makeXRCompatible() umgestellt werden.

Siehe auch

XRWebGLLayer XRCompositionLayer XRProjectionLayer XRQuadLayer XRWebGLBinding XRSession.updateRenderState() XRSession EventTarget