Signatur
Beschreibung
Die Eigenschaft transform eines XRQuadLayer gibt an, wo sich die flache, rechteckige Ebene im Raum befindet und wie sie ausgerichtet ist. Der Wert ist ein XRRigidTransform (Position + Orientierung als Quaternion) und bezieht sich immer auf den Referenzraum, der in XRQuadLayer.space hinterlegt ist, z. B. einen local- oder local-floor-Raum.
Die Eigenschaft ist lesbar und schreibbar. Beim Erzeugen der Ebene mit XRWebGLBinding.createQuadLayer() legt man die Anfangslage über die Option transform fest. Später kann man durch Zuweisen eines neuen XRRigidTransform die Ebene verschieben oder drehen – etwa um ein Menü vor dem Nutzer zu platzieren oder einem Controller folgen zu lassen.
Typische Anwendungsfälle sind UI-Paneele, Videoflächen oder Textanzeigen, die über Compositor-Layer besonders scharf dargestellt werden. Die Mitte der Quad-Ebene liegt am Ursprung des Transforms; die Ebene erstreckt sich in der x/y-Ebene, ihre Vorderseite zeigt in Richtung +z.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | XRRigidTransform | Beim Schreiben: neues XRRigidTransform mit Position (DOMPointInit) und Orientierung (Quaternion) relativ zu space. |
Rückgabewert
XRRigidTransform, das Versatz und Orientierung der Ebene relativ zu ihrem space beschreibt.Beispiele
Quad-Ebene 2 m vor dem Nutzer erzeugen
const session = await navigator.xr.requestSession('immersive-vr', {
requiredFeatures: ['layers']
});
const gl = document.createElement('canvas').getContext('webgl2', { xrCompatible: true });
const binding = new XRWebGLBinding(session, gl);
const refSpace = await session.requestReferenceSpace('local');
const quadLayer = binding.createQuadLayer({
space: refSpace,
viewPixelWidth: 1024,
viewPixelHeight: 768,
width: 1.0, // Meter
height: 0.75,
transform: new XRRigidTransform({ x: 0, y: 1.5, z: -2 })
});
session.updateRenderState({ layers: [quadLayer] });
console.log(quadLayer.transform.position.z);Ebene nachträglich verschieben und drehen
// 45° um die y-Achse drehen (Quaternion)
const angle = Math.PI / 4;
quadLayer.transform = new XRRigidTransform(
{ x: 1, y: 1.5, z: -2 },
{ x: 0, y: Math.sin(angle / 2), z: 0, w: Math.cos(angle / 2) }
);
const { position, orientation } = quadLayer.transform;
console.log(position.x, orientation.y.toFixed(3));Paneel folgt der Blickrichtung (im Frame-Loop)
const onFrame = (time, frame) => {
const pose = frame.getViewerPose(refSpace);
if (pose) {
// Ebene 1,5 m vor die Kopfposition setzen
const offset = new XRRigidTransform({ x: 0, y: 0, z: -1.5 });
const m = new DOMMatrix(pose.transform.matrix)
.multiply(new DOMMatrix(offset.matrix));
quadLayer.transform = new XRRigidTransform(
{ x: m.m41, y: m.m42, z: m.m43 },
pose.transform.orientation
);
}
session.requestAnimationFrame(onFrame);
};
session.requestAnimationFrame(onFrame);// Wichtig · Fallstricke
- Kompatibilität: Die WebXR Layers API ist experimentell und wird praktisch nur in XR-Browsern wie dem Meta Quest Browser unterstützt. Die Session muss mit dem Feature
'layers'angefordert werden; vorher mit'XRQuadLayer' in windowprüfen. XRRigidTransformist unveränderlich: Ändern vontransform.position.xwirkt nicht. Um die Lage zu ändern, muss man immer ein neues Objekt zuweisen.- Das Quaternion für die Orientierung muss normiert sein, sonst wird es normalisiert oder löst einen Fehler aus.
- Der Transform bezieht sich auf
space. Wirdspacegeändert (z. B. vonlocalaufviewer), ändert sich die Bedeutung desselben Transforms. Bei einemviewer-Raum ist die Ebene an den Kopf gekoppelt, was Übelkeit auslösen kann. - Es wird in Metern gerechnet; die Vorderseite der Ebene zeigt in Richtung +z. Liegt sie vor dem Nutzer bei negativem z, ist sie automatisch zu ihm hin ausgerichtet.