VRDisplay.capabilities — Eigenschaft · JavaScript-Referenz

Signatur

VRDisplay.capabilities

Beschreibung

Die nur lesbare Eigenschaft capabilities der Schnittstelle VRDisplay gibt ein VRDisplayCapabilities-Objekt zurück. Es beschreibt, was das angeschlossene VR-Gerät kann. Mit diesen Angaben passt eine Anwendung ihr Verhalten an das Headset an, bevor sie die Präsentation startet.

Das Objekt enthält folgende booleschen bzw. numerischen Eigenschaften:

hasPosition: Das Gerät kann seine Position im Raum erfassen (6DoF).
hasOrientation: Das Gerät kann seine Ausrichtung erfassen (veraltet, auch in WebVR selbst).
hasExternalDisplay: Das Display ist vom Hauptbildschirm getrennt, z. B. ein Desktop-Headset.
canPresent: Das Gerät kann Inhalte über requestPresent() anzeigen.
maxLayers: Die höchste Anzahl an VRLayerInit-Ebenen, die requestPresent() annimmt.

Typische Einsatzfälle: Bei reinem Rotations-Tracking (3DoF) eine Ersatzsteuerung anbieten, den „VR betreten“-Button nur zeigen, wenn canPresent wahr ist, oder bei hasExternalDisplay zusätzlich eine Spiegelung auf dem Hauptbildschirm rendern.

Achtung: Die gesamte WebVR-API ist veraltet und wurde durch die WebXR Device API ersetzt. Für neue Projekte sollte man sie nicht mehr verwenden.

Rückgabewert

Typ

VRDisplayCapabilities

Beschreibung

Ein Objekt mit den Eigenschaften hasPosition, hasOrientation, hasExternalDisplay, canPresent (jeweils boolean) und maxLayers (number).

Beispiele

Fähigkeiten des ersten VR-Displays auslesen

const zeigeFaehigkeiten = 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-Display gefunden.');
    return;
  }
  const { capabilities, displayName } = displays[0];
  console.log(`Gerät: ${displayName}`);
  console.log(`Positionserfassung: ${capabilities.hasPosition}`);
  console.log(`Externes Display: ${capabilities.hasExternalDisplay}`);
  console.log(`Kann präsentieren: ${capabilities.canPresent}`);
  console.log(`Max. Ebenen: ${capabilities.maxLayers}`);
};

zeigeFaehigkeiten();

Gerät: Oculus Rift CV1 Positionserfassung: true Externes Display: true Kann präsentieren: true Max. Ebenen: 1

„VR betreten“-Button nur bei Präsentationsfähigkeit anzeigen

const vrButton = document.querySelector('#enter-vr');
const canvas = document.querySelector('#scene');

const initVR = async () => {
  const [display] = (await navigator.getVRDisplays?.()) ?? [];
  if (!display || !display.capabilities.canPresent) {
    vrButton.hidden = true;
    return;
  }
  vrButton.hidden = false;
  vrButton.addEventListener('click', async () => {
    try {
      await display.requestPresent([{ source: canvas }]);
    } catch (err) {
      console.error('Präsentation fehlgeschlagen:', err);
    }
  });
};

initVR();

Steuerung an 3DoF- bzw. 6DoF-Tracking anpassen

const waehleSteuerung = (display) => {
  const { hasPosition } = display.capabilities;
  if (hasPosition) {
    // Nutzer kann sich physisch im Raum bewegen
    return 'roomscale';
  }
  // Nur Kopfdrehung: Teleport-Steuerung per Controller/Tastatur anbieten
  return 'teleport';
};

navigator.getVRDisplays?.().then(([display]) => {
  if (display) console.log('Steuerungsmodus:', waehleSteuerung(display));
});

Steuerungsmodus: teleport

// Wichtig · Fallstricke

Veraltet: WebVR wurde nie standardisiert und ist aus Chrome und Firefox entfernt worden. Nutze stattdessen WebXR (navigator.xr, XRSession). Dort prüft man z. B. mit navigator.xr.isSessionSupported('immersive-vr'), ob eine Präsentation möglich ist, und wählt über Referenzräume wie 'local-floor' oder 'bounded-floor', ob Positions-Tracking genutzt wird.
Browser-Kompatibilität: Früher nur in Firefox (Windows), in Chrome hinter einem Flag bzw. in Origin Trials, in Samsung Internet und im Oculus Browser verfügbar. Die Unterstützung vorher immer mit 'getVRDisplays' in navigator prüfen.
hasOrientation war schon innerhalb von WebVR als veraltet markiert. Verlass dich nicht darauf, dass diese Eigenschaft vorhanden ist.
Die Eigenschaft ist schreibgeschützt. Wertzuweisungen werden stillschweigend ignoriert (im Strict Mode gibt es einen TypeError).
maxLayers war in der Praxis fast immer 1. Übergib requestPresent() nicht mehr Ebenen als angegeben, sonst wird das Promise abgelehnt.

Siehe auch

VRDisplay VRDisplayCapabilities Navigator.getVRDisplays() VRDisplay.requestPresent() XRSystem.isSessionSupported() XRSession Navigator.mediaCapabilities