Signatur
Beschreibung
Die Eigenschaft transform einer XREquirectLayer enthält ein XRRigidTransform-Objekt. Es beschreibt den Versatz (position) und die Ausrichtung (orientation) der Ebene relativ zu dem Referenzraum, der in XREquirectLayer.space hinterlegt ist. Da eine equirektanguläre Ebene auf die Innenseite einer Kugel projiziert wird, bestimmt transform vor allem den Mittelpunkt dieser Kugel und ihre Drehung. So legt man zum Beispiel fest, in welche Richtung die „Vorderseite“ eines 360°-Panoramas oder -Videos zeigt.
Die Eigenschaft kann gelesen und geschrieben werden. Man setzt sie meist schon beim Erzeugen über XRWebGLBinding.createEquirectLayer() oder XRMediaBinding.createEquirectLayer() (Option transform). Später lässt sie sich zur Laufzeit ersetzen, etwa um ein Panorama zu drehen. Weil XRRigidTransform unveränderlich ist, muss man dafür immer ein neues Objekt zuweisen. Die Felder eines bestehenden Objekts lassen sich nicht ändern.
Typische Einsatzfälle sind 360°-Videoplayer, Panorama-Fotobetrachter und Skyboxen in WebXR-Anwendungen. Der Compositor zeichnet die Ebene direkt und damit in hoher Qualität, ohne dass die Szene selbst neu gerendert werden muss.
Rückgabewert
XRRigidTransform mit position (DOMPointReadOnly), orientation (Quaternion als DOMPointReadOnly), matrix und inverse. Wird beim Erzeugen kein Wert angegeben, ist es die Identitätstransformation.Beispiele
360°-Video-Ebene mit Transformation erzeugen
const session = await navigator.xr.requestSession('immersive-vr', {
requiredFeatures: ['layers']
});
const refSpace = await session.requestReferenceSpace('local');
const video = document.querySelector('video');
const mediaBinding = new XRMediaBinding(session);
// Kugelmittelpunkt 1,6 m über dem Ursprung (Augenhöhe)
const layer = mediaBinding.createEquirectLayer(video, {
space: refSpace,
layout: 'mono',
transform: new XRRigidTransform({ x: 0, y: 1.6, z: 0 })
});
session.updateRenderState({ layers: [layer] });
console.log(layer.transform.position.y);Panorama zur Laufzeit um 90° drehen
// Quaternion für eine Drehung um die Y-Achse
const yRotation = (deg) => {
const rad = (deg * Math.PI) / 180;
return { x: 0, y: Math.sin(rad / 2), z: 0, w: Math.cos(rad / 2) };
};
// XRRigidTransform ist unveränderlich – neues Objekt zuweisen
const { position } = layer.transform;
layer.transform = new XRRigidTransform(
{ x: position.x, y: position.y, z: position.z },
yRotation(90)
);
console.log(layer.transform.orientation.y.toFixed(3));Aktuelle Transformation auslesen
const { position, orientation } = layer.transform;
console.log(`Position: ${position.x}, ${position.y}, ${position.z}`);
console.log(`Orientierung (w): ${orientation.w}`);// Wichtig · Fallstricke
- Kompatibilität: Die WebXR Layers API ist experimentell und wird im Wesentlichen nur von Chromium-basierten XR-Browsern unterstützt, etwa dem Meta Quest Browser. Firefox und Safari unterstützen sie nicht. Das Feature
'layers'muss beirequestSession()angefordert werden. Außerdem ist ein sicherer Kontext (HTTPS) nötig. - Nicht direkt verändern:
layer.transform.position.x = 2hat keine Wirkung, weilXRRigidTransformund seineDOMPointReadOnly-Werte schreibgeschützt sind. Weise immer ein neuesXRRigidTransformzu. - Die Quaternion für
orientationwird normalisiert. Ungültige Werte wie ein Nullvektor lösen einen Fehler aus. - Die Transformation gilt relativ zu
layer.space. Wird der Referenzraum gewechselt, z. B. von'local'auf'local-floor', ändert sich die tatsächliche Position der Ebene. - Einen Skalierungsanteil gibt es nicht. Die Größe der Kugel wird über
radiusgesteuert, der sichtbare Ausschnitt übercentralHorizontalAngle,upperVerticalAngleundlowerVerticalAngle.