Signatur
Beschreibung
Die schreibgeschützte Eigenschaft transform eines XRReferenceSpaceEvent beschreibt, wie sich der native Ursprung eines XRReferenceSpace durch das Ereignis verschoben hat. Derzeit gibt es nur einen Ereignistyp dieser Art: reset. Er wird ausgelöst, wenn das XR-System den Ursprung neu festlegt, z. B. weil der Nutzer das Tracking neu zentriert, das Headset nach einem Tracking-Verlust neu initialisiert wurde oder die Grenzen eines bounded-floor-Raums neu eingerichtet wurden.
Der Wert ist ein XRRigidTransform. Er gibt die Pose des neuen Ursprungs im alten Koordinatensystem an. Haben Sie Objekte, Wegpunkte oder Ankerpositionen in Koordinaten des alten Referenzraums gespeichert, rechnen Sie diese mit transform.inverse in das neue System um. Dann bleiben virtuelle Inhalte an ihrem Platz in der realen Welt, statt mit dem Ursprung mitzuspringen.
Kann das System die Verschiebung nicht bestimmen (etwa nach einem vollständigen Tracking-Verlust), ist transform null. Ihre Anwendung sollte die Szene dann sinnvoll neu ausrichten, statt eine Korrektur zu versuchen.
Rückgabewert
null, wenn die Verschiebung unbekannt ist.Beispiele
Auf ein reset-Ereignis reagieren (addEventListener)
const session = await navigator.xr.requestSession('immersive-vr');
const refSpace = await session.requestReferenceSpace('local-floor');
refSpace.addEventListener('reset', (event) => {
const t = event.transform;
if (t) {
const { x, y, z } = t.position;
console.log(`Ursprung verschoben um (${x.toFixed(2)}, ${y.toFixed(2)}, ${z.toFixed(2)})`);
} else {
console.log('Ursprung zurückgesetzt – Verschiebung unbekannt');
}
});Gespeicherte Objektpositionen in das neue Koordinatensystem umrechnen
// Punkt mit einer spaltenweise gespeicherten 4x4-Matrix transformieren
const transformPoint = (m, p) => ({
x: m[0] * p.x + m[4] * p.y + m[8] * p.z + m[12],
y: m[1] * p.x + m[5] * p.y + m[9] * p.z + m[13],
z: m[2] * p.x + m[6] * p.y + m[10] * p.z + m[14]
});
// Positionen virtueller Objekte, gespeichert im Referenzraum
const placedObjects = [
{ name: 'Würfel', position: { x: 1, y: 0, z: -2 } }
];
refSpace.onreset = (event) => {
if (!event.transform) {
placedObjects.length = 0; // Neu platzieren lassen
return;
}
// alt -> neu: Umkehrung der Pose des neuen Ursprungs
const m = event.transform.inverse.matrix;
for (const obj of placedObjects) {
obj.position = transformPoint(m, obj.position);
}
console.log(placedObjects[0].position);
};Ereignis zu Testzwecken selbst erzeugen
const fakeTransform = new XRRigidTransform({ x: 0.5, y: 0, z: 0 });
const evt = new XRReferenceSpaceEvent('reset', {
referenceSpace: refSpace,
transform: fakeTransform
});
refSpace.dispatchEvent(evt);
console.log(evt.transform.position.x);// Wichtig · Fallstricke
- Richtung beachten:
transformgibt die Pose des neuen Ursprungs im alten System an. Um alte Koordinaten in neue umzurechnen, brauchen Sietransform.inverse. Diese Richtung wird leicht verwechselt. - Auf
nullprüfen: Ist die Verschiebung unbekannt, ist der Wertnull. Lesen Sie ihn deshalb nie ohne Prüfung aus. - Von Ihnen mit
getOffsetReferenceSpace()abgeleitete Räume folgen dem neuen Ursprung automatisch. Selbst gespeicherte Rohkoordinaten müssen Sie dagegen selbst umrechnen. XRAnchor-Posen (Erweiterung für räumliche Anker) werden vom System aktuell gehalten und brauchen in der Regel keine Korrektur.- Bei
viewer-Referenzräumen gibt es keinreset-Ereignis. - Kompatibilität: Die Eigenschaft funktioniert nur in sicheren Kontexten (HTTPS) und in Browsern mit WebXR-Unterstützung (Chrome/Edge, Meta Quest Browser, Samsung Internet). Safari und Firefox-Desktop unterstützen sie nicht. Die Eigenschaft ist experimentell.