Signatur
Beschreibung
Die Eigenschaft upperVerticalAngle der Schnittstelle XREquirectLayer legt fest, bis zu welchem Winkel über dem Horizont die Kugel reicht, auf die das equirektangulare Bild (z. B. ein 360°-Foto oder -Video) projiziert wird. Der Wert wird in Bogenmaß angegeben und liegt zwischen -π/2 (senkrecht nach unten) und π/2 (senkrecht nach oben, Zenit).
Zusammen mit lowerVerticalAngle und centralHorizontalAngle beschreibt die Eigenschaft den sichtbaren Kugelausschnitt. Mit den Standardwerten (upperVerticalAngle = π/2, lowerVerticalAngle = -π/2, centralHorizontalAngle = 2π) entsteht eine vollständige Kugel. Verkleinert man den oberen Winkel, wird die Kugel oben „abgeschnitten“ – sinnvoll etwa für 180°-Inhalte oder Panoramen, die keinen Himmel enthalten.
Der Anfangswert wird meist beim Erzeugen der Ebene über XRWebGLBinding.createEquirectLayer() im Init-Objekt übergeben. Da die Eigenschaft beschreibbar ist, kann sie auch zur Laufzeit geändert werden, etwa um einen Ausschnitt dynamisch zu vergrößern oder zu verkleinern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | Math.PI / 2 | Beim Setzen: neuer oberer vertikaler Winkel in Bogenmaß, sinnvoller Bereich -Math.PI / 2 bis Math.PI / 2. Sollte größer als lowerVerticalAngle sein. |
Rückgabewert
Beispiele
Equirect-Ebene mit halber Kugel (nur obere Hemisphäre) erzeugen
const startXR = async (canvas) => {
const session = await navigator.xr.requestSession('immersive-vr', {
requiredFeatures: ['layers']
});
const gl = canvas.getContext('webgl2', { xrCompatible: true });
const refSpace = await session.requestReferenceSpace('local');
const binding = new XRWebGLBinding(session, gl);
const equirect = binding.createEquirectLayer({
space: refSpace,
viewPixelWidth: 2048,
viewPixelHeight: 1024,
radius: 10,
centralHorizontalAngle: 2 * Math.PI,
upperVerticalAngle: Math.PI / 2, // bis zum Zenit
lowerVerticalAngle: 0 // bis zum Horizont
});
session.updateRenderState({ layers: [equirect] });
console.log(equirect.upperVerticalAngle.toFixed(4));
return { session, equirect };
};Winkel in Grad umrechnen und zur Laufzeit ändern
const degToRad = (deg) => deg * Math.PI / 180;
const radToDeg = (rad) => rad * 180 / Math.PI;
// equirect: vorhandene XREquirectLayer
const setUpperAngle = (equirect, degrees) => {
// auf gültigen Bereich begrenzen
const clamped = Math.min(90, Math.max(-90, degrees));
equirect.upperVerticalAngle = degToRad(clamped);
console.log(`Oberer Winkel: ${radToDeg(equirect.upperVerticalAngle)}°`);
};
setUpperAngle(equirect, 45);Symmetrischen Ausschnitt für 180°-Video einstellen
// Vertikal ±60°, horizontal 180°
const configure180 = (equirect) => {
equirect.centralHorizontalAngle = Math.PI;
equirect.upperVerticalAngle = Math.PI / 3;
equirect.lowerVerticalAngle = -Math.PI / 3;
const span = equirect.upperVerticalAngle - equirect.lowerVerticalAngle;
console.log(`Vertikale Öffnung: ${Math.round(span * 180 / Math.PI)}°`);
};
configure180(equirect);// Wichtig · Fallstricke
- Bogenmaß, nicht Grad: Ein häufiger Fehler ist
upperVerticalAngle = 90. Richtig istMath.PI / 2. - Wertebereich: Laut Spezifikation werden Werte auf
-π/2bisπ/2begrenzt. Achte darauf, dassupperVerticalAnglegrößer alslowerVerticalAnglebleibt, sonst ist der Kugelausschnitt leer bzw. das Ergebnis undefiniert. - Textur-Mapping: Die Textur wird auf den gewählten Ausschnitt gestreckt. Passt das Seitenverhältnis des Bildes nicht zu den Winkeln, wirkt der Inhalt verzerrt.
- Kompatibilität: Die WebXR Layers API ist experimentell und wird derzeit praktisch nur im Meta Quest Browser unterstützt. Das Feature
'layers'muss beirequestSession()angefordert werden; vorher mittypeof XRWebGLBinding !== 'undefined'und'createEquirectLayer' in XRWebGLBinding.prototypeprüfen. Nur in sicheren Kontexten (HTTPS) verfügbar.