VRFrameData — Schnittstelle · JavaScript-Referenz

Signatur

interface VRFrameData

Beschreibung

VRFrameData gehört zur veralteten WebVR API und bündelt alles, was zum stereoskopischen Rendern eines Frames nötig ist. Du erzeugst ein Objekt einmalig mit new VRFrameData() und übergibst es dann in jedem Frame an VRDisplay.getFrameData(frameData). Die Methode füllt das Objekt mit den aktuellen Werten und gibt true zurück, wenn das geklappt hat.

Diese Eigenschaften sind schreibgeschützt:

timestamp – ein DOMHighResTimeStamp, der sich bei jedem Aktualisieren der Daten erhöht.
leftProjectionMatrix / rightProjectionMatrix – Float32Array mit 16 Werten (4×4-Matrix, spaltenweise gespeichert) als Projektionsmatrix für das jeweilige Auge.
leftViewMatrix / rightViewMatrix – Float32Array mit 16 Werten, die View-Matrix für das jeweilige Auge (Pose und Augenabstand sind schon eingerechnet).
pose – ein VRPose-Objekt mit Position, Orientierung, Geschwindigkeit und Beschleunigung des Headsets.

Typischerweise nutzt du das Objekt in einer Render-Schleife mit VRDisplay.requestAnimationFrame(): Daten abrufen, die Szene für das linke und das rechte Auge jeweils in eine Hälfte des Canvas zeichnen und zum Schluss VRDisplay.submitFrame() aufrufen. Die Matrizen kannst du direkt an WebGL-Uniforms übergeben, zum Beispiel mit gl.uniformMatrix4fv().

Rückgabewert

Typ

VRFrameData

Beschreibung

Der Konstruktor new VRFrameData() erzeugt ein leeres Objekt. VRDisplay.getFrameData() füllt es mit Werten.

Beispiele

Instanziierung und einmaliges Befüllen

if ('getVRDisplays' in navigator) {
  const displays = await navigator.getVRDisplays();
  if (displays.length > 0) {
    const vrDisplay = displays[0];
    const frameData = new VRFrameData();
    const ok = vrDisplay.getFrameData(frameData);
    console.log('Erfolgreich:', ok);
    console.log('Zeitstempel:', frameData.timestamp);
    console.log('Matrix-Länge:', frameData.leftViewMatrix.length);
  }
} else {
  console.log('WebVR wird nicht unterstützt – bitte WebXR verwenden.');
}

Erfolgreich: true Zeitstempel: 1234.56 Matrix-Länge: 16

Stereo-Render-Schleife mit WebGL

const canvas = document.querySelector('canvas');
const gl = canvas.getContext('webgl');
const frameData = new VRFrameData(); // einmal erzeugen, dann wiederverwenden

// Platzhalter: zeichnet die Szene mit den übergebenen Matrizen
const drawScene = (projection, view) => {
  // gl.uniformMatrix4fv(projLoc, false, projection);
  // gl.uniformMatrix4fv(viewLoc, false, view);
  // gl.drawArrays(...);
};

const startVR = async () => {
  const [vrDisplay] = await navigator.getVRDisplays();
  await vrDisplay.requestPresent([{ source: canvas }]);

  const onFrame = () => {
    vrDisplay.requestAnimationFrame(onFrame);
    vrDisplay.getFrameData(frameData);

    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
    const half = canvas.width / 2;

    // Linkes Auge
    gl.viewport(0, 0, half, canvas.height);
    drawScene(frameData.leftProjectionMatrix, frameData.leftViewMatrix);

    // Rechtes Auge
    gl.viewport(half, 0, half, canvas.height);
    drawScene(frameData.rightProjectionMatrix, frameData.rightViewMatrix);

    vrDisplay.submitFrame();
  };
  vrDisplay.requestAnimationFrame(onFrame);
};

document.querySelector('#enter-vr').addEventListener('click', startVR);

Kopfposition und Orientierung aus der Pose auslesen

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

if (vrDisplay.getFrameData(frameData)) {
  const { position, orientation } = frameData.pose;
  // Beide Werte können null sein, z. B. bei reinem 3DoF-Tracking
  console.log('Position:', position ? Array.from(position) : 'nicht verfügbar');
  console.log('Orientierung (Quaternion):', orientation ? Array.from(orientation) : 'nicht verfügbar');
}

Position: [0, 1.6, 0] Orientierung (Quaternion): [0, 0, 0, 1]

// Wichtig · Fallstricke

Veraltet: WebVR und damit auch VRFrameData sind ein Experiment, das nie standardisiert wurde. Die meisten Browser haben die API entfernt oder nie unterstützt. Früher lief sie in Firefox (auf Windows) und in Chrome nur hinter einem Flag. Für neue Projekte solltest du die WebXR Device API verwenden, dort übernehmen XRFrame, XRViewerPose und XRView diese Aufgaben.

Prüfe vor der Nutzung, ob der Browser die API kennt, z. B. mit 'VRFrameData' in window oder 'getVRDisplays' in navigator.
Erzeuge das VRFrameData-Objekt nur einmal und verwende es in jedem Frame wieder. Ein neues Objekt pro Frame erzeugt unnötige Arbeit für die Speicherbereinigung und kann zu Rucklern führen.
Die Matrizen sind spaltenweise gespeichert, so wie WebGL sie erwartet. Übergib an gl.uniformMatrix4fv() deshalb transpose = false.
pose.position und pose.orientation können null sein, wenn das Gerät die entsprechenden Werte nicht erfassen kann.
Nur sicherer Kontext (HTTPS): Wo die API noch existiert, ist sie in unsicheren Kontexten oft gesperrt.

Siehe auch

VRDisplay VRDisplay.getFrameData() VRPose VRDisplay.submitFrame() XRFrame XRViewerPose