XRQuadLayer.height — Eigenschaft · JavaScript-Referenz

Signatur

XRQuadLayer.height

Beschreibung

Eine XRQuadLayer ist eine flache, rechteckige Composition-Ebene, die der XR-Compositor direkt in die Szene zeichnet. Sie eignet sich für Texte, Menüs, Videos oder 2D-Oberflächen, weil sie schärfer dargestellt wird als eine Textur auf einem WebGL-Mesh. Die Eigenschaft height legt die physische Höhe dieses Rechtecks in Metern fest. Zusammen mit width bestimmt sie also die Größe der Ebene in der Welt.

Den Anfangswert übergibt man beim Erzeugen über XRWebGLBinding.createQuadLayer() im Init-Objekt (height, Standardwert 1.0). Danach lässt sich die Eigenschaft jederzeit neu setzen, etwa zum Animieren, zum Skalieren oder um ein Seitenverhältnis einzuhalten. Die Änderung gilt ab dem nächsten Frame.

Wichtig: height hat nichts mit der Auflösung der Textur zu tun. Die Pixelgröße legen viewPixelHeight und viewPixelWidth beim Erzeugen fest. Damit Inhalte nicht verzerrt werden, sollte das Verhältnis width / height dem Verhältnis der Pixelmaße entsprechen.

Rückgabewert

Typ

number

Beschreibung

Höhe der Ebene in Metern als Gleitkommazahl. Standardwert ist 1.0, wenn beim Erzeugen nichts angegeben wurde.

Beispiele

Quad-Ebene mit Höhe erzeugen und auslesen

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 quadLayer = binding.createQuadLayer({
  space: refSpace,
  viewPixelWidth: 1024,
  viewPixelHeight: 512,
  width: 1.6,   // 1,6 m breit
  height: 0.8,  // 0,8 m hoch – Seitenverhältnis 2:1 wie die Textur
  transform: new XRRigidTransform({ x: 0, y: 1.5, z: -2 })
});

session.updateRenderState({ layers: [quadLayer] });
console.log(`Höhe: ${quadLayer.height} m`);

Höhe: 0.8 m

Seitenverhältnis beim Skalieren beibehalten

// Ebene proportional skalieren, ohne den Inhalt zu verzerren
const resizeQuad = (layer, newWidth) => {
  const aspect = layer.height / layer.width;
  layer.width = newWidth;
  layer.height = newWidth * aspect;
};

resizeQuad(quadLayer, 2.4);
console.log(quadLayer.width, quadLayer.height);

2.4 1.2

Höhe im Render-Loop animieren (Aufklapp-Effekt)

const targetHeight = 0.8;
let start = null;

const onXRFrame = (time, frame) => {
  start ??= time;
  const t = Math.min((time - start) / 500, 1); // 500 ms Dauer
  quadLayer.height = Math.max(targetHeight * t, 0.001);
  frame.session.requestAnimationFrame(onXRFrame);
};

session.requestAnimationFrame(onXRFrame);

// Wichtig · Fallstricke

Kompatibilität: Die WebXR Layers API ist experimentell. Sie wird im Wesentlichen vom Meta Quest Browser unterstützt, in Chromium nur teilweise und hinter Flags. Firefox und Safari unterstützen sie nicht. Die Session muss mit dem Feature 'layers' angefordert werden. Alternativ gibt es das Polyfill von Meta.
Einheit: Der Wert ist in Metern im Referenzraum angegeben, nicht in Pixeln. Wer die Auflösung ändern will, muss eine neue Ebene mit anderem viewPixelHeight erzeugen.
Verzerrung: Passt width/height nicht zum Pixel-Seitenverhältnis, wird der Inhalt gestreckt oder gestaucht.
Ungültige Werte: Setzen Sie nur positive, endliche Zahlen. Wie 0, negative Werte oder NaN behandelt werden, hängt von der Implementierung ab. Die Ebene kann dann unsichtbar werden oder es wird ein Fehler ausgelöst.
Die Ebene ist zentriert an ihrem transform. Eine größere Höhe verlängert sie also gleichmäßig nach oben und unten.

Siehe auch

XRQuadLayer XRQuadLayer.width XRQuadLayer.transform XRWebGLBinding.createQuadLayer() XRCompositionLayer SpeechGrammar.weight