VRStageParameters — Schnittstelle · JavaScript-Referenz

Signatur

interface VRStageParameters

Beschreibung

Das Interface VRStageParameters gehört zur veralteten WebVR API. Es beschreibt die begehbare Fläche (die „Bühne“) bei Headsets, die Erfahrungen im Raummaßstab (room-scale) unterstützen, etwa HTC Vive oder Oculus Rift mit Guardian. Ein Objekt davon bekommt man über die Eigenschaft VRDisplay.stageParameters. Wenn das Gerät keine Bühne kennt, ist der Wert null.

Das Interface hat drei schreibgeschützte Eigenschaften:

sittingToStandingTransform: ein Float32Array mit 16 Werten, also eine 4×4-Matrix in Spaltenreihenfolge (column-major). Sie überführt Koordinaten aus dem sitzenden Bezugsraum von VRPose in einen stehenden Raum, dessen Ursprung in der Bodenmitte der Bühne liegt.
sizeX: die Breite der Spielfläche in Metern (X-Achse).
sizeY: die Tiefe der Spielfläche in Metern. Trotz des Namens ist das die Z-Achse der Szene.

Man braucht das Interface, um virtuelle Böden auf die richtige Höhe zu setzen, Begrenzungen („Chaperone“) zu zeichnen oder Objekte so zu verteilen, dass Nutzer sie physisch erreichen können. Neue Projekte sollten stattdessen die WebXR Device API verwenden, zum Beispiel XRSession.requestReferenceSpace('bounded-floor') mit XRBoundedReferenceSpace.boundsGeometry.

Rückgabewert

Typ

VRStageParameters | null

Beschreibung

Man erhält das Objekt über VRDisplay.stageParameters. Der Wert ist null, wenn das Gerät keinen Raummaßstab unterstützt oder noch keine Bühne eingerichtet wurde.

Beispiele

Bühnengröße des Headsets auslesen

const zeigeBuehne = async () => {
  if (!navigator.getVRDisplays) {
    console.log('WebVR wird nicht unterstützt');
    return;
  }
  const displays = await navigator.getVRDisplays();
  if (displays.length === 0) {
    console.log('Kein VR-Gerät gefunden');
    return;
  }
  const stage = displays[0].stageParameters;
  if (stage === null) {
    console.log('Kein Raummaßstab verfügbar');
    return;
  }
  console.log(`Spielfläche: ${stage.sizeX.toFixed(2)} m × ${stage.sizeY.toFixed(2)} m`);
};

zeigeBuehne();

Spielfläche: 3.00 m × 2.50 m

Sitz-zu-Steh-Matrix auf eine Kopfposition anwenden

// 4×4-Matrix (column-major) auf einen Punkt [x, y, z] anwenden
const transformiere = (m, [x, y, z]) => [
  m[0] * x + m[4] * y + m[8] * z + m[12],
  m[1] * x + m[5] * y + m[9] * z + m[13],
  m[2] * x + m[6] * y + m[10] * z + m[14]
];

const [display] = await navigator.getVRDisplays();
const frameData = new VRFrameData();

const render = () => {
  display.getFrameData(frameData);
  const stage = display.stageParameters;
  const pos = frameData.pose.position ?? [0, 0, 0];
  if (stage) {
    const [x, y, z] = transformiere(stage.sittingToStandingTransform, pos);
    console.log(`Kopfhöhe über dem Boden: ${y.toFixed(2)} m`);
  }
  display.requestAnimationFrame(render);
};

display.requestAnimationFrame(render);

Kopfhöhe über dem Boden: 1.68 m

Begrenzungsrechteck für die Szene berechnen

const berechneGrenzen = (stage) => {
  const halbeBreite = stage.sizeX / 2;
  const halbeTiefe = stage.sizeY / 2; // sizeY entspricht der Z-Achse!
  return [
    [-halbeBreite, 0, -halbeTiefe],
    [ halbeBreite, 0, -halbeTiefe],
    [ halbeBreite, 0,  halbeTiefe],
    [-halbeBreite, 0,  halbeTiefe]
  ];
};

const [display] = await navigator.getVRDisplays();
if (display?.stageParameters) {
  console.log(berechneGrenzen(display.stageParameters));
}

[[-1.5, 0, -1.25], [1.5, 0, -1.25], [1.5, 0, 1.25], [-1.5, 0, 1.25]]

// Wichtig · Fallstricke

Veraltet: WebVR wurde nie standardisiert und ist aus allen aktuellen Browsern entfernt. Früher lief es in Firefox (bis Version 97), in älteren Chrome-Versionen nur hinter einem Flag und im Samsung Internet Browser. In der WebXR Device API übernimmt XRBoundedReferenceSpace diese Aufgabe.

sizeX und sizeY können 0 sein, wenn das Gerät nur stehende Nutzung ohne definierte Fläche meldet. Prüfe den Wert, bevor du damit rechnest.
sizeY ist die Tiefe (Z-Achse), nicht die Höhe. Verwechslungen sind ein häufiger Fehler.
Die Matrix ist in Spaltenreihenfolge gespeichert. Sie lässt sich direkt an WebGL (uniformMatrix4fv) oder an Bibliotheken wie gl-matrix übergeben.
Die Bühne ist nur ein Rechteck. Unregelmäßige Grenzen gibt es erst in WebXR, dort über boundsGeometry.
Die Werte können sich zur Laufzeit ändern, zum Beispiel wenn der Nutzer die Fläche neu einrichtet. Lies stageParameters deshalb regelmäßig neu aus, statt es einmalig zwischenzuspeichern.
WebVR braucht einen sicheren Kontext (HTTPS) und kann durch Berechtigungsrichtlinien gesperrt sein.

Siehe auch

VRDisplay VRDisplay.stageParameters VRPose VRFrameData Navigator.getVRDisplays() XRBoundedReferenceSpace