new XRRigidTransform() — Methode · JavaScript-Referenz

Signatur

new XRRigidTransform(position, orientation)

Beschreibung

Der Konstruktor XRRigidTransform() erzeugt eine starre Transformation. Sie setzt sich aus einer Verschiebung (position) und einer Drehung (orientation) zusammen. Skalierung und Scherung gibt es dabei nicht, deshalb heißt sie „starr“. In der WebXR Device API beschreibt sie, wo sich ein Objekt, Referenzraum oder Blickpunkt befindet und wie er ausgerichtet ist.

Meist braucht man den Konstruktor, um einen versetzten Referenzraum zu erzeugen. Dazu übergibt man das Objekt an XRReferenceSpace.getOffsetReferenceSpace(). So lässt sich etwa der Startpunkt der Betrachterin verschieben oder eine Teleport- bzw. Drehsteuerung umsetzen. Auch bei der Hit-Test-API (XRRay) und bei Anker-Positionen werden solche Transformationen benötigt.

Beide Parameter sind DOMPointInit-Objekte. Bei position muss w gleich 1 sein. orientation ist ein Quaternion {x, y, z, w}, das der Browser automatisch auf Länge 1 normalisiert. Die erzeugte Instanz ist unveränderlich: position, orientation, matrix (ein Float32Array mit 16 Werten, spaltenweise geordnet) und inverse kann man nur lesen.

Parameter

Name	Typ	Default	Beschreibung
$position	DOMPointInit	{x: 0, y: 0, z: 0, w: 1}	Verschiebung in Metern. `w` muss `1` sein, sonst wird ein `TypeError` geworfen. Fehlende Koordinaten werden mit `0` belegt.
$orientation	DOMPointInit	{x: 0, y: 0, z: 0, w: 1}	Drehung als Einheitsquaternion. Der Wert wird automatisch normalisiert. Hat das Quaternion die Länge 0, wird ein `InvalidStateError` geworfen.

Rückgabewert

Typ

XRRigidTransform

Beschreibung

Neue, unveränderliche Transformation mit den Eigenschaften position, orientation, matrix und inverse.

Beispiele

Einfache Transformation erzeugen und auslesen

// 1 m nach oben, 2 m nach vorn (−Z), keine Drehung
const transform = new XRRigidTransform({ x: 0, y: 1, z: -2 });

console.log(transform.position.y);     // 1
console.log(transform.orientation.w);  // 1
console.log(transform.matrix.length);  // 16

1 1 16

Drehung um die Y-Achse als Quaternion

// 90° um die Y-Achse drehen
const winkel = Math.PI / 2;
const orientation = {
  x: 0,
  y: Math.sin(winkel / 2),
  z: 0,
  w: Math.cos(winkel / 2)
};

const gedreht = new XRRigidTransform({ x: 0, y: 0, z: 0 }, orientation);
console.log(gedreht.orientation.y.toFixed(3)); // 0.707

// Die Umkehrung dreht wieder zurück
console.log(gedreht.inverse.orientation.y.toFixed(3)); // -0.707

0.707 -0.707

Teleport per versetztem Referenzraum

let refSpace;

const startXR = async () => {
  const session = await navigator.xr.requestSession('immersive-vr');
  refSpace = await session.requestReferenceSpace('local-floor');
  session.requestAnimationFrame(onFrame);
};

// Betrachterin an Zielpunkt (x, z) versetzen.
// Der Referenzraum wird entgegengesetzt verschoben, daher die Vorzeichen.
const teleport = (x, z) => {
  const offset = new XRRigidTransform({ x: -x, y: 0, z: -z });
  refSpace = refSpace.getOffsetReferenceSpace(offset);
};

const onFrame = (time, frame) => {
  const pose = frame.getViewerPose(refSpace);
  if (pose) {
    // ... Szene mit pose.views rendern
  }
  frame.session.requestAnimationFrame(onFrame);
};

document.querySelector('#vr-button').addEventListener('click', startXR);

// Wichtig · Fallstricke

Browser-Unterstützung: WebXR steht in Chromium-Browsern (Chrome, Edge, Samsung Internet, Meta Quest Browser) und in Safari auf visionOS zur Verfügung. Firefox für Desktop unterstützt es standardmäßig nicht. Die API gibt es nur in sicheren Kontexten (HTTPS oder localhost). Prüfe die Verfügbarkeit mit 'XRRigidTransform' in window oder navigator.xr.
w bei position: Ist position.w ungleich 1, wird ein TypeError geworfen.
Quaternion statt Eulerwinkel: orientation erwartet ein Quaternion und keine Winkel in Grad oder Bogenmaß. Ein Quaternion der Länge 0 führt zu einem InvalidStateError. Andere Werte werden stillschweigend normalisiert.
Unveränderlich: Einzelne Werte lassen sich nachträglich nicht ändern. Für jede neue Pose legt man eine neue Instanz an. Wer das pro Frame tut, sollte auf den Speicherdruck durch die Garbage Collection achten.
Richtung beim Versatz: getOffsetReferenceSpace() verschiebt den Ursprung des Referenzraums. Die Betrachterin scheint sich deshalb in die entgegengesetzte Richtung zu bewegen.
Einheiten sind Meter. Das Koordinatensystem ist rechtshändig: +Y zeigt nach oben, −Z nach vorn.

Siehe auch

new DOMPointReadOnly() new DataTransfer() new WebTransport() new GravitySensor() new RTCRtpScriptTransform()