Signatur
Beschreibung
Die Eigenschaft orientation der Schnittstelle XRCubeLayer legt fest, wie die Würfel-Ebene gegenüber ihrem Koordinatensystem (XRCubeLayer.space) gedreht ist. Der Wert ist ein DOMPointReadOnly, der eine Einheitsquaternion enthält: x, y und z bilden den Vektoranteil, w den Skalaranteil.
Eine Cube-Layer wird meist für Skyboxen und Umgebungs-Panoramen genutzt. Sie wird immer so gezeichnet, als läge sie unendlich weit entfernt. Deshalb spielt nur die Rotation des Referenzraums eine Rolle, seine Position wird ignoriert. Mit orientation dreht man die Umgebung, ohne die Texturen neu zu rendern. So lässt sich etwa der Himmel nach Norden ausrichten oder langsam rotieren lassen.
Die Eigenschaft ist les- und schreibbar. Einen Startwert übergibt man schon beim Erzeugen über die Option orientation von XRWebGLBinding.createCubeLayer(). Später weist man einfach einen neuen DOMPointReadOnly zu. Die Änderung wirkt ab dem nächsten Frame, in dem die Ebene in session.updateRenderState({ layers }) eingetragen ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value Pflicht | DOMPointReadOnly | DOMPointReadOnly(0, 0, 0, 1) | Beim Setzen: Einheitsquaternion {x, y, z, w}, die die neue Ausrichtung beschreibt. |
Rückgabewert
(0, 0, 0, 1), also keine Drehung.Beispiele
Cube-Layer mit Anfangsausrichtung 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');
// 90° um die Y-Achse: (0, sin(45°), 0, cos(45°))
const halb = Math.PI / 4;
const skybox = binding.createCubeLayer({
space: refSpace,
viewPixelWidth: 1024,
viewPixelHeight: 1024,
layout: 'mono',
orientation: new DOMPointReadOnly(0, Math.sin(halb), 0, Math.cos(halb))
});
session.updateRenderState({ layers: [skybox] });
const { x, y, z, w } = skybox.orientation;
console.log(x, y.toFixed(3), z, w.toFixed(3));Skybox pro Frame langsam drehen
// Hilfsfunktion: Quaternion für eine Drehung um die Y-Achse
const yRotation = (winkel) =>
new DOMPointReadOnly(0, Math.sin(winkel / 2), 0, Math.cos(winkel / 2));
const onFrame = (time, frame) => {
// eine volle Umdrehung pro Minute
const winkel = (time / 60000) * 2 * Math.PI;
skybox.orientation = yRotation(winkel);
frame.session.requestAnimationFrame(onFrame);
};
session.requestAnimationFrame(onFrame);Ausrichtung zurücksetzen und Einheitslänge prüfen
skybox.orientation = new DOMPointReadOnly(0, 0, 0, 1);
const { x, y, z, w } = skybox.orientation;
const laenge = Math.hypot(x, y, z, w);
console.log(`Keine Drehung: ${w === 1}, Länge: ${laenge}`);// Wichtig · Fallstricke
- Experimentell: Die WebXR Layers API wird kaum unterstützt, vor allem vom Meta Quest Browser und von Chromium mit aktiviertem Flag. Firefox und Safari unterstützen sie nicht. Das Feature
'layers'muss beirequestSession()angefordert werden. Prüfe vorher mit'XRCubeLayer' in window, ob die Schnittstelle vorhanden ist. - Nur Einheitsquaternionen: Die Quaternion sollte die Länge 1 haben. Ob ein nicht normierter Wert beim Setzen normiert, abgelehnt oder unverändert verwendet wird, hängt vom Browser ab und ist nicht verlässlich. Normiere deshalb selbst.
- Der Wert ist ein unveränderlicher
DOMPointReadOnly.layer.orientation.y = 1hat keine Wirkung. Weise immer ein neues Objekt zu. - Die Position von
spacewird ignoriert. Eine Cube-Layer verschiebt sich nie mit, sie dreht sich nur. - Eine Cube-Layer kann nur in einem
'immersive-vr'-Kontext genutzt werden. Als Layout sind nur'mono'oder'stereo'erlaubt.