XREquirectLayer.lowerVerticalAngle — Eigenschaft · JavaScript-Referenz

Signatur

XREquirectLayer.lowerVerticalAngle

Beschreibung

Eine XREquirectLayer bildet eine äquirektangulare Textur, z. B. ein 360°-Foto oder -Video, auf die Innenseite einer Kugel ab. lowerVerticalAngle gibt an, wie weit diese Abbildung vom Äquator der Kugel aus nach unten reicht. Der Wert ist eine Gleitkommazahl in Radiant im Bereich von -π/2 (Südpol, direkt unter der Betrachterin oder dem Betrachter) bis π/2 (Nordpol). Der Standardwert ist -π/2. Damit reicht die Textur bis ganz nach unten.

Zusammen mit upperVerticalAngle (obere Grenze, Standardwert π/2) und centralHorizontalAngle (horizontale Ausdehnung, Standardwert 2π) legt die Eigenschaft fest, welcher Ausschnitt der Kugel gefüllt wird. Das ist zum Beispiel bei diesen Inhalten nützlich:

Himmelskuppeln: Mit lowerVerticalAngle = 0 wird nur die obere Halbkugel gefüllt. Den Boden rendert man als eigene Geometrie.
180°-Panoramen oder Videos mit begrenztem Blickfeld: Hier wird nur ein Teil des Vollbildwinkels benötigt.
Panoramen ohne Boden: Aufnahmen, bei denen z. B. das Stativ unten wegretuschiert werden soll.

Den Anfangswert setzt man meist beim Erzeugen der Ebene über das Init-Objekt von XRWebGLBinding.createEquirectLayer(). Weil die Eigenschaft schreibbar ist, kann man sie auch später zur Laufzeit ändern. Die Änderung wird beim nächsten Frame angewendet.

Parameter

Name	Typ	Default	Beschreibung
$value	number	-Math.PI / 2	Nur beim Setzen: der neue untere Winkel in Radiant. Sinnvoll ist ein Wert zwischen `-Math.PI / 2` und `Math.PI / 2`, der kleiner als `upperVerticalAngle` ist.

Rückgabewert

Typ

number

Beschreibung

Der aktuelle untere vertikale Winkel der Kugel in Radiant, als Gleitkommazahl.

Beispiele

Himmelskuppel: nur die obere Halbkugel füllen

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

  const skyLayer = binding.createEquirectLayer({
    space: refSpace,
    viewPixelWidth: 4096,
    viewPixelHeight: 1024,
    layout: 'mono',
    radius: 0,                    // 0 = unendlich weit entfernt
    centralHorizontalAngle: Math.PI * 2,
    upperVerticalAngle: Math.PI / 2,
    lowerVerticalAngle: 0         // Textur endet am Horizont
  });

  session.updateRenderState({ layers: [skyLayer] });
  console.log(skyLayer.lowerVerticalAngle);
};

startSkyDome();

Standardwert auslesen und in Grad umrechnen

const toDegrees = (rad) => (rad * 180) / Math.PI;

// equirectLayer wurde ohne lowerVerticalAngle erzeugt
console.log(equirectLayer.lowerVerticalAngle);
console.log(`${toDegrees(equirectLayer.lowerVerticalAngle)}°`);

-1.5707963267948966 -90°

Unteren Rand zur Laufzeit ändern (z. B. Boden einblenden)

const setFloorCutoff = (layer, degrees) => {
  const rad = (degrees * Math.PI) / 180;
  // auf den gültigen Bereich begrenzen und unterhalb der oberen Grenze halten
  const clamped = Math.max(-Math.PI / 2, Math.min(rad, layer.upperVerticalAngle - 0.001));
  layer.lowerVerticalAngle = clamped;
};

// Panorama nur bis 30° unter den Horizont zeigen
setFloorCutoff(equirectLayer, -30);
console.log(equirectLayer.lowerVerticalAngle.toFixed(4));

-0.5236

// Wichtig · Fallstricke

Einheit: Der Wert ist in Radiant angegeben, nicht in Grad. Ein typischer Fehler ist lowerVerticalAngle = -45. Richtig ist -Math.PI / 4.
Wertebereich: Werte außerhalb von -π/2 bis π/2 sind nicht sinnvoll. Bei manchen Implementierungen werden sie begrenzt. Ist lowerVerticalAngle größer oder gleich upperVerticalAngle, bleibt der sichtbare Bereich leer. Die Werte deshalb vorher selbst prüfen.
Texturverzerrung: Die ganze Textur wird auf den gewählten Winkelbereich gestreckt. Wer den Bereich verkleinert, sollte auch das Seitenverhältnis von viewPixelWidth und viewPixelHeight anpassen. Sonst wird das Bild gestaucht.
Voraussetzungen: Die Ebene gibt es nur, wenn die Sitzung mit dem Feature 'layers' angefordert wurde. Außerdem muss der Kontext ein sicherer Kontext (HTTPS) sein.
Kompatibilität: Die WebXR Layers API ist experimentell. Sie wird im Wesentlichen vom Meta Quest Browser unterstützt, in Firefox und Safari fehlt sie. Vor der Nutzung prüfen, z. B. mit typeof XREquirectLayer !== 'undefined', oder einen Polyfill verwenden, etwa den WebXR Layers Polyfill.

Siehe auch

XREquirectLayer XREquirectLayer.upperVerticalAngle XREquirectLayer.centralHorizontalAngle XREquirectLayer.radius XRWebGLBinding.createEquirectLayer() XRCylinderLayer