Signatur
Beschreibung
Die Eigenschaft layers von XRRenderState gibt die Ebenen (Layers) zurück, die der XR-Kompositor aktuell darstellt. Die Reihenfolge im Array legt fest, in welcher Reihenfolge gezeichnet wird: Das erste Element liegt ganz hinten, das letzte ganz vorn. Eine Ebene kann eine XRProjectionLayer, XRQuadLayer, XRCylinderLayer, XREquirectLayer, XRCubeLayer oder eine XRWebGLLayer sein.
Gesetzt wird der Wert nicht direkt, sondern über XRSession.updateRenderState({ layers: [...] }). Die Änderung wird erst mit dem nächsten Frame wirksam; bis dahin liefert session.renderState.layers noch den alten Stand.
Mit mehreren Ebenen lassen sich z. B. Texte, Videos oder Bedienoberflächen als eigene Quad- oder Zylinder-Ebenen rendern. Der Kompositor kann sie direkt und schärfer darstellen als Inhalte, die in die Hauptszene gerendert werden, und spart dabei Rechenleistung.
Wurde die Sitzung nur mit baseLayer eingerichtet oder wurden nie Ebenen gesetzt, ist layers ein leeres Array. baseLayer und layers schließen sich gegenseitig aus.
Rückgabewert
XRLayer-Objekten (von hinten nach vorn). Ohne gesetzte Ebenen ist es leer.Beispiele
Projektions- und Quad-Ebene setzen und auslesen
const startXR = async () => {
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 projLayer = binding.createProjectionLayer({ textureType: 'texture' });
const quadLayer = binding.createQuadLayer({
space: refSpace,
viewPixelWidth: 1024,
viewPixelHeight: 512,
layout: 'mono'
});
// Reihenfolge: Szene hinten, UI-Quad vorn
session.updateRenderState({ layers: [projLayer, quadLayer] });
session.requestAnimationFrame(() => {
// Ab dem nächsten Frame ist der neue Zustand aktiv
console.log(session.renderState.layers.length);
});
};Ebene ein- und ausblenden, ohne das Array direkt zu verändern
const toggleLayer = (session, layer) => {
const current = [...session.renderState.layers];
const index = current.indexOf(layer);
if (index === -1) {
current.push(layer); // ganz vorn einfügen
} else {
current.splice(index, 1);
}
session.updateRenderState({ layers: current });
};Unterstützung prüfen und auf baseLayer zurückfallen
const setupLayers = (session, gl) => {
if ('XRWebGLBinding' in window && 'createProjectionLayer' in XRWebGLBinding.prototype) {
const binding = new XRWebGLBinding(session, gl);
session.updateRenderState({ layers: [binding.createProjectionLayer()] });
} else {
session.updateRenderState({ baseLayer: new XRWebGLLayer(session, gl) });
}
console.log('layers' in session.renderState ? 'Layers-API vorhanden' : 'nur baseLayer');
};// Wichtig · Fallstricke
- Schreibgeschützt: Das Array ist eingefroren.
push()oder das direkte Zuweisen haben keine Wirkung bzw. werfen im Strict Mode einenTypeError. Ändern lässt es sich nur überupdateRenderState(). - Nicht mit
baseLayerkombinieren: WerdenbaseLayerundlayerszusammen gesetzt, wirftupdateRenderState()einenNotSupportedError. - Ohne das Feature
'layers'beirequestSession()ist nur eine einzige Ebene erlaubt. Dieselbe Ebene darf nicht doppelt im Array stehen, und Ebenen aus einer anderen Sitzung sind nicht zulässig. - Änderungen gelten erst ab dem nächsten Animations-Frame.
- Kompatibilität: Die Eigenschaft ist experimentell und wird vor allem von Chromium-basierten Browsern und dem Meta Quest Browser unterstützt. Sie funktioniert nur in sicheren Kontexten (HTTPS). Firefox und Safari bieten sie bisher nicht an.
- Viele Ebenen belasten den Kompositor. Setze Quad- und Zylinder-Ebenen daher gezielt ein, etwa für Text oder Video.