XREquirectLayer.space — Eigenschaft · JavaScript-Referenz

Signatur

XREquirectLayer.space

Beschreibung

Die Eigenschaft space der Schnittstelle XREquirectLayer gibt den Referenzraum an, in dem der Layer verankert ist. Ein Equirect-Layer bildet eine Textur im äquirektangulären Format (z. B. ein 360°-Foto oder -Video) auf die Innenseite einer Kugel ab. Die Position und Ausrichtung dieser Kugel ergibt sich aus space zusammen mit der Eigenschaft transform.

Der Anfangswert stammt aus der Option space, die du beim Erzeugen über XRWebGLBinding.createEquirectLayer() angibst. Die Eigenschaft ist nicht schreibgeschützt: Du kannst sie zur Laufzeit ändern, um den Layer z. B. von einem festen Raum ("local") an einen anderen Referenzraum oder an einen versetzten Raum aus getOffsetReferenceSpace() zu hängen.

Typische Einsatzfälle sind 360°-Panoramen, Skyboxen und Videoplayer, die der Compositor des Browsers direkt und besonders scharf darstellt, ohne dass du die Kugel selbst in WebGL rendern musst. Der Referenzraum bestimmt, ob das Panorama in der Welt bleibt oder sich mit dem Nutzer mitbewegt.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	XRSpace		Beim Setzen: der neue Raum, in dem der Layer verankert wird, z. B. ein `XRReferenceSpace` aus `session.requestReferenceSpace()`.

Rückgabewert

Typ

XRSpace

Beschreibung

Der aktuell zugewiesene Raum des Layers, meist ein XRReferenceSpace.

Beispiele

Equirect-Layer im lokalen Referenzraum erzeugen

const startPanorama = async (gl) => {
  const session = await navigator.xr.requestSession('immersive-vr', {
    requiredFeatures: ['layers']
  });
  const refSpace = await session.requestReferenceSpace('local');
  const binding = new XRWebGLBinding(session, gl);

  const equirect = binding.createEquirectLayer({
    space: refSpace,
    viewPixelWidth: 4096,
    viewPixelHeight: 2048,
    layout: 'mono'
  });

  session.updateRenderState({ layers: [equirect] });
  console.log(equirect.space === refSpace);
  return { session, equirect, refSpace };
};

true

Panorama zur Laufzeit drehen – über einen versetzten Raum

// Dreht das Panorama um 90° um die Y-Achse
const rotatePanorama = (equirect, baseSpace) => {
  const angle = Math.PI / 2;
  const orientation = {
    x: 0,
    y: Math.sin(angle / 2),
    z: 0,
    w: Math.cos(angle / 2)
  };
  const offset = new XRRigidTransform({ x: 0, y: 0, z: 0 }, orientation);
  equirect.space = baseSpace.getOffsetReferenceSpace(offset);
  console.log('Neuer Raum gesetzt:', equirect.space instanceof XRReferenceSpace);
};

Neuer Raum gesetzt: true

Zwischen weltfestem und nutzerbezogenem Raum wechseln

const toggleAnchor = async (session, equirect) => {
  const [local, localFloor] = await Promise.all([
    session.requestReferenceSpace('local'),
    session.requestReferenceSpace('local-floor')
  ]);
  // Wechselt zwischen zwei Referenzräumen
  equirect.space = equirect.space === local ? localFloor : local;
};

// Wichtig · Fallstricke

Experimentell: Die WebXR Layers API wird bisher nur in Chromium-basierten Browsern mit WebXR-Unterstützung (u. a. Meta Quest Browser) angeboten. Firefox und Safari unterstützen sie nicht. Prüfe vorher, ob XRWebGLBinding.prototype.createEquirectLayer vorhanden ist.
Die Sitzung muss mit dem Feature 'layers' angefordert werden (requiredFeatures oder optionalFeatures), sonst sind Layer-Objekte nicht verfügbar.
Für Equirect-Layer muss space ein XRReferenceSpace sein. Andere Räume wie ein XRSpace aus einer Eingabequelle führen beim Erzeugen zu einem TypeError.
Die endgültige Lage ergibt sich aus space und transform. Wenn du nur eines davon änderst, kann das zu unerwarteten Ausrichtungen führen.
Mit einem 'viewer'-Raum bewegt sich das Panorama mit dem Kopf mit. Das wirkt unnatürlich und kann Übelkeit auslösen, deshalb eher 'local' oder 'local-floor' verwenden.
Referenzräume sind an ihre Sitzung gebunden. Einen Raum aus einer anderen XRSession zuzuweisen, ist ungültig.

Siehe auch

XREquirectLayer XREquirectLayer.transform XRWebGLBinding.createEquirectLayer() XRReferenceSpace XRSession.requestReferenceSpace() XRReferenceSpace.getOffsetReferenceSpace() XRQuadLayer.space