Signatur
Beschreibung
Die Eigenschaft space des Interfaces XRCubeLayer verweist auf ein XRSpace-Objekt – meist einen XRReferenceSpace. Dieser Raum ist das Koordinatensystem, in dem der Compositor die Würfel-Ebene darstellt. Ein XRCubeLayer wird typischerweise für Skyboxen oder 360°-Umgebungen verwendet, die aus sechs Würfelseiten (einer Cubemap) bestehen.
Bei Würfel-Ebenen gilt eine Besonderheit: Es wird nur die Ausrichtung des Raums berücksichtigt, die Position spielt keine Rolle. Die Ebene wird so dargestellt, als läge sie unendlich weit entfernt, und der Nutzer befindet sich immer im Mittelpunkt des Würfels. Zusätzlich lässt sich die Ausrichtung über die Eigenschaft orientation feinjustieren.
Der Wert wird beim Erzeugen der Ebene über die Option space von XRWebGLBinding.createCubeLayer() festgelegt. Die Eigenschaft ist beschreibbar: Sie können später einen anderen Raum zuweisen, etwa nach einem reset-Ereignis des Referenzraums oder wenn Sie die Skybox mit einem versetzten Raum (getOffsetReferenceSpace()) drehen möchten.
Rückgabewert
XRSpace-Objekt derselben XRSession übergeben werden.Beispiele
Skybox als Würfel-Ebene anlegen und Raum auslesen
const session = await navigator.xr.requestSession('immersive-vr', {
requiredFeatures: ['layers']
});
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2', { xrCompatible: true });
const refSpace = await session.requestReferenceSpace('local');
const binding = new XRWebGLBinding(session, gl);
const skybox = binding.createCubeLayer({
space: refSpace,
viewPixelWidth: 1024,
viewPixelHeight: 1024,
layout: 'mono'
});
session.updateRenderState({ layers: [skybox] });
console.log(skybox.space === refSpace);Skybox um 90° um die Hochachse drehen
// Nur die Ausrichtung zählt – die Position des Offsets wird ignoriert
const angle = Math.PI / 2;
const rotation = new XRRigidTransform(
{ x: 0, y: 0, z: 0 },
{ x: 0, y: Math.sin(angle / 2), z: 0, w: Math.cos(angle / 2) }
);
skybox.space = refSpace.getOffsetReferenceSpace(rotation);
console.log(skybox.space instanceof XRReferenceSpace);Raum nach einem Reset des Referenzraums neu zuweisen
refSpace.addEventListener('reset', () => {
// Skybox wieder an den (neu kalibrierten) Referenzraum koppeln
skybox.space = refSpace;
console.log('Skybox-Raum aktualisiert');
});// Wichtig · Fallstricke
- Nur Ausrichtung: Die Position von
spacewird bei Würfel-Ebenen ignoriert. Wer die Skybox verschieben will, erreicht damit nichts – sie bleibt immer um den Betrachter zentriert. - Raumtyp: Ein
'viewer'-Raum lässt die Skybox an der Kopfbewegung „kleben“ und führt schnell zu Übelkeit. Verwenden Sie'local','local-floor'oder'unbounded'. - Der zugewiesene Raum muss zur selben
XRSessiongehören wie die Ebene. Andernfalls kann eine Ausnahme ausgelöst werden oder die Ebene wird nicht dargestellt. - Kompatibilität: Die WebXR Layers API ist experimentell und nur in wenigen Browsern verfügbar (vor allem im Meta Quest Browser, teilweise in Chromium hinter einem Flag). Die Session muss mit dem Feature
'layers'angefordert werden. Prüfen Sie vorab, obXRWebGLBinding.prototype.createCubeLayerexistiert, und sehen Sie eine Alternative vor (z. B. eine selbst gerenderte Skybox in der Projektionsebene). Nur in sicheren Kontexten (HTTPS) verfügbar.