XRCylinderLayer.space — Eigenschaft · JavaScript-Referenz

Signatur

XRCylinderLayer.space

Beschreibung

Die Eigenschaft space des Interfaces XRCylinderLayer ist ein XRSpace. Er gibt das Koordinatensystem vor, auf das sich die transform der Zylinderebene bezieht. So wird festgelegt, ob die Ebene fest im Raum stehen bleibt (z. B. mit einem local- oder local-floor-Referenzraum) oder ob sie mit dem Kopf des Nutzers mitwandert (viewer-Referenzraum).

Die Eigenschaft ist les- und schreibbar. Ihr Anfangswert kommt aus der Option space, die man XRWebGLBinding.createCylinderLayer() übergibt. Diese Option ist Pflicht. Soll die Ebene später in einem anderen Bezugssystem liegen, weist man zur Laufzeit einfach einen neuen XRSpace zu. Das ist praktisch, wenn man etwa ein Panel vom Kopf lösen und in der Welt „ablegen“ möchte.

Zylinderebenen eignen sich gut für gekrümmte Oberflächen wie Menüs, Textpanels oder Videos, die den Nutzer umgeben. Das Endgerät (der Compositor) zeichnet sie direkt und damit besonders scharf. Welcher Raum passt, hängt vom Anwendungsfall ab: Fest verankerte Inhalte gehören in einen Welt-Referenzraum, Anzeigen im Stil eines HUD in den viewer-Raum.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	XRSpace		Beim Setzen: ein `XRSpace` (meist ein `XRReferenceSpace` aus `XRSession.requestReferenceSpace()`). Er muss aus derselben `XRSession` stammen, zu der die Ebene gehört.

Rückgabewert

Typ

XRSpace

Beschreibung

Der aktuelle Referenzraum, auf den sich Position und Ausrichtung der Zylinderebene (transform) beziehen.

Beispiele

Zylinderebene in einem festen Welt-Raum anlegen

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

const cylinderLayer = xrGlBinding.createCylinderLayer({
  space: refSpace,               // Pflichtangabe
  viewPixelWidth: 1024,
  viewPixelHeight: 512,
  radius: 2,
  centralAngle: Math.PI / 2,
  aspectRatio: 2,
  transform: new XRRigidTransform({ x: 0, y: 1.5, z: 0 })
});

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

true

Panel zwischen Kopf-Bindung und Welt-Verankerung umschalten

const viewerSpace = await session.requestReferenceSpace('viewer');
const worldSpace = await session.requestReferenceSpace('local');

let followHead = false;

const toggleFollow = () => {
  followHead = !followHead;
  // Neuer Bezugsraum – transform wird nun relativ dazu interpretiert
  cylinderLayer.space = followHead ? viewerSpace : worldSpace;
  cylinderLayer.transform = followHead
    ? new XRRigidTransform({ x: 0, y: 0, z: 0 })
    : new XRRigidTransform({ x: 0, y: 1.6, z: 0 });
  console.log(`Panel folgt dem Kopf: ${followHead}`);
};

session.addEventListener('select', toggleFollow);

Panel folgt dem Kopf: true

Aktuellen Raum für Pose-Abfragen nutzen

session.requestAnimationFrame(function onFrame(time, frame) {
  // Pose der Ebene relativ zum Welt-Raum ermitteln
  const pose = frame.getPose(cylinderLayer.space, worldSpace);
  if (pose) {
    const { x, y, z } = pose.transform.position;
    console.log(`Ebenen-Ursprung: ${x.toFixed(2)}, ${y.toFixed(2)}, ${z.toFixed(2)}`);
  }
  session.requestAnimationFrame(onFrame);
});

Ebenen-Ursprung: 0.00, 0.00, 0.00

// Wichtig · Fallstricke

Kompatibilität: Die WebXR Layers API ist experimentell und nur in wenigen Browsern verfügbar, vor allem im Meta Quest Browser und in Chromium mit XR-Unterstützung. Die Session muss mit requiredFeatures: ['layers'] (oder optionalFeatures) angefordert werden. Außerdem ist ein sicherer Kontext (HTTPS) nötig.
Auch transform bezieht sich immer auf space. Wer den Raum wechselt, ohne die Transformation anzupassen, lässt die Ebene oft an eine unerwartete Stelle springen, etwa in den Kopf des Nutzers oder auf den Boden.
Ein viewer-Raum koppelt die Ebene fest an die Kopfbewegung. Das kann bei großen Panels Unbehagen oder Übelkeit auslösen. Für längeres Lesen ist eine Welt-Verankerung meist angenehmer.
Ein XRSpace aus einer anderen oder bereits beendeten Session ist ungültig. Raumobjekte werden nicht zwischen Sessions geteilt.
Nach einem reset-Ereignis des Referenzraums kann sich der Ursprung verschieben. Die Ebene springt dann mit, wenn man nicht nachkorrigiert.

Siehe auch

XRCylinderLayer XRCylinderLayer.transform XRWebGLBinding.createCylinderLayer() XRSpace XRReferenceSpace XRSession.requestReferenceSpace() XRQuadLayer.space