Signatur
Beschreibung
Die Eigenschaft aspectRatio eines XRCylinderLayer legt das Verhältnis von Breite zu Höhe des sichtbaren Abschnitts der Zylinderfläche fest. Ein Zylinder-Layer zeigt Inhalte auf einer gekrümmten Fläche an, die den Betrachter teilweise umgibt – ideal für gekrümmte Bildschirme, Menüs, Panoramen oder Videoflächen in immersiven WebXR-Sitzungen.
Die Breite des sichtbaren Bogens ergibt sich aus radius * centralAngle (Bogenlänge). Die Höhe der Fläche wird daraus über das Seitenverhältnis berechnet: höhe = (radius * centralAngle) / aspectRatio. Ein größerer Wert erzeugt also eine flachere, breitere Fläche, ein kleinerer eine höhere.
Die Eigenschaft ist lesbar und schreibbar. Der Anfangswert wird beim Erzeugen über XRWebGLBinding.createCylinderLayer() bzw. XRMediaBinding.createCylinderLayer() im Options-Objekt übergeben (Standard: 2.0). Änderungen wirken sich auf die Darstellung ab dem nächsten Frame aus – die Pixelauflösung der Textur (viewPixelWidth/viewPixelHeight) bleibt dabei unverändert.
Typischerweise wählt man das Seitenverhältnis passend zum darzustellenden Inhalt, z. B. 16 / 9 für ein Video, damit die Inhalte nicht gestaucht oder gestreckt erscheinen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | 2.0 | Beim Setzen: neues Seitenverhältnis (Breite / Höhe) als positive Gleitkommazahl. |
Rückgabewert
Beispiele
Zylinder-Layer mit festem Seitenverhältnis anlegen
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 cylinderLayer = binding.createCylinderLayer({
space: refSpace,
viewPixelWidth: 1920,
viewPixelHeight: 1080,
radius: 2.0,
centralAngle: Math.PI / 3,
aspectRatio: 16 / 9
});
session.updateRenderState({ layers: [cylinderLayer] });
console.log(cylinderLayer.aspectRatio.toFixed(3));Höhe der Zylinderfläche berechnen
const getCylinderHeight = (layer) =>
(layer.radius * layer.centralAngle) / layer.aspectRatio;
// Annahme: cylinderLayer aus dem vorherigen Beispiel
console.log(`Höhe: ${getCylinderHeight(cylinderLayer).toFixed(2)} m`);Seitenverhältnis an ein Video anpassen
const video = document.querySelector('video');
const mediaBinding = new XRMediaBinding(session);
const videoLayer = mediaBinding.createCylinderLayer(video, {
space: refSpace,
centralAngle: Math.PI / 2
});
// Sobald die Metadaten geladen sind, Verhältnis korrigieren
video.addEventListener('loadedmetadata', () => {
videoLayer.aspectRatio = video.videoWidth / video.videoHeight;
console.log('Neues Verhältnis:', videoLayer.aspectRatio);
});
session.updateRenderState({ layers: [videoLayer] });// Wichtig · Fallstricke
- Experimentell: Die WebXR Layers API wird derzeit praktisch nur im Meta Quest Browser (und teils hinter Flags in Chromium) unterstützt. Vor der Nutzung per Feature-Erkennung prüfen, z. B.
'XRCylinderLayer' in window, und das Feature'layers'beirequestSession()anfordern. - Das Seitenverhältnis beeinflusst nur die geometrische Form der Fläche, nicht die Texturauflösung. Passen
viewPixelWidth/viewPixelHeightnicht zum Verhältnis, wird der Inhalt verzerrt dargestellt. - Die Breite hängt allein von
radiusundcentralAngleab – eine Änderung vonaspectRatioändert daher nur die Höhe. - Nur positive, endliche Werte sind sinnvoll;
0, negative Zahlen oderNaNführen zu undefiniertem bzw. unsichtbarem Ergebnis. - Nur in sicheren Kontexten (HTTPS) verfügbar.