XRRigidTransform.matrix — Eigenschaft · JavaScript-Referenz

Signatur

XRRigidTransform.matrix

Beschreibung

Die schreibgeschützte Eigenschaft matrix eines XRRigidTransform-Objekts gibt die Transformation aus Position (position) und Ausrichtung (orientation) als homogene 4×4-Matrix zurück. Die Matrix steckt in einem Float32Array mit 16 Elementen in Spaltenreihenfolge (column-major), also genau in dem Format, das WebGL mit uniformMatrix4fv() und Bibliotheken wie gl-matrix oder three.js erwarten.

Eine starre Transformation (rigid transform) besteht nur aus Rotation und Translation, ohne Skalierung oder Scherung. Die Matrix wendet zuerst die Rotation und danach die Verschiebung an. Die Translation steht in den Elementen [12], [13] und [14], das letzte Element [15] ist immer 1.

In der Praxis brauchen Sie matrix vor allem im Render-Loop einer WebXR-Sitzung: Aus XRView.transform.inverse.matrix wird die View-Matrix für jedes Auge, aus XRPose.transform.matrix die Modellmatrix von Controllern oder Ankern. Die Matrix wird beim ersten Zugriff aus position und orientation berechnet und danach zwischengespeichert.

Rückgabewert

Typ

Float32Array

Beschreibung

Ein Float32Array mit 16 Werten in Spaltenreihenfolge, das die Rotation und Translation der Transformation als 4×4-Matrix enthält.

Beispiele

Matrix einer einfachen Verschiebung auslesen

// Transformation: 1 m nach oben, 2 m nach vorn, ohne Rotation
const transform = new XRRigidTransform({ x: 0, y: 1, z: -2 });
const m = transform.matrix;

console.log(m.length);
console.log(Array.from(m).join(', '));
// Die Translation steht in den Elementen 12–14
console.log(m[12], m[13], m[14]);

16 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, -2, 1 0 1 -2

View- und Projektionsmatrizen im WebXR-Render-Loop an WebGL übergeben

const onXRFrame = (time, frame) => {
  const session = frame.session;
  session.requestAnimationFrame(onXRFrame);

  const pose = frame.getViewerPose(refSpace);
  if (!pose) return;

  const layer = session.renderState.baseLayer;
  gl.bindFramebuffer(gl.FRAMEBUFFER, layer.framebuffer);

  for (const view of pose.views) {
    const vp = layer.getViewport(view);
    gl.viewport(vp.x, vp.y, vp.width, vp.height);

    // View-Matrix = Inverse der Kamerapose
    gl.uniformMatrix4fv(uView, false, view.transform.inverse.matrix);
    gl.uniformMatrix4fv(uProjection, false, view.projectionMatrix);
    drawScene();
  }
};

Controller-Pose als Modellmatrix für three.js verwenden

import * as THREE from 'three';

const controllerMesh = new THREE.Mesh(
  new THREE.BoxGeometry(0.05, 0.05, 0.2),
  new THREE.MeshNormalMaterial()
);
controllerMesh.matrixAutoUpdate = false;

const updateController = (frame, inputSource, refSpace) => {
  const pose = frame.getPose(inputSource.gripSpace, refSpace);
  if (pose) {
    // fromArray erwartet ebenfalls Spaltenreihenfolge
    controllerMesh.matrix.fromArray(pose.transform.matrix);
    controllerMesh.visible = true;
  } else {
    controllerMesh.visible = false;
  }
};

Rotation und Translation kombiniert

// 90° um die Y-Achse drehen, dann 3 m entlang X verschieben
const s = Math.SQRT1_2;
const t = new XRRigidTransform(
  { x: 3, y: 0, z: 0 },
  { x: 0, y: s, z: 0, w: s }
);
console.log(Array.from(t.matrix, (v) => Math.round(v)).join(', '));

0, 0, -1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 3, 0, 0, 1

// Wichtig · Fallstricke

Spaltenreihenfolge: Die Werte sind column-major gespeichert. Wer die Matrix wie eine zeilenweise Tabelle liest oder an eine Bibliothek mit Zeilenreihenfolge übergibt, bekommt eine transponierte und damit falsche Transformation.
Nicht beschreibbar im Sinne der Transformation: Die Eigenschaft selbst ist schreibgeschützt. Den Inhalt des Float32Array zu ändern wirkt nicht auf position oder orientation zurück und kann bei zwischengespeicherten Matrizen zu Inkonsistenzen führen. Legen Sie stattdessen ein neues XRRigidTransform an oder kopieren Sie die Matrix mit .slice().
Gültigkeit: Die Posen-Objekte aus XRFrame gelten nur während des aktuellen Frames. Wenn Sie Matrizen über mehrere Frames brauchen, speichern Sie eine Kopie.
Kompatibilität: WebXR gibt es nur in sicheren Kontexten (HTTPS) und vor allem in Chromium-basierten Browsern sowie in XR-Headset-Browsern. Firefox und Safari auf dem Desktop unterstützen es nicht. Prüfen Sie die Unterstützung mit 'xr' in navigator.
Ein Konstruktor-Aufruf mit nicht normalisiertem Quaternion wird automatisch normalisiert. Die Matrix bildet deshalb immer eine reine Rotation ohne Skalierung ab.

Siehe auch

XRRigidTransform XRRigidTransform.position XRRigidTransform.orientation XRRigidTransform.inverse XRView.projectionMatrix XRPose.transform VTTRegion.id