Signatur
Beschreibung
Die Eigenschaft session des Interfaces XRVisibilityMaskChangeEvent verweist auf die XRSession, zu der das Ereignis gehört. Das Ereignis visibilitymaskchange wird auf einer XR-Sitzung ausgelöst, wenn das XR-Gerät eine neue oder geänderte Sichtbarkeitsmaske für eine Ansicht (z. B. das linke oder rechte Auge) meldet. Die Maske beschreibt, welcher Teil der Ansicht für den Nutzer überhaupt sichtbar ist. Durch die Linsenform von Headsets sind oft Bereiche am Rand nicht sichtbar.
Über session kommen Sie ohne Umweg über Closures oder globale Variablen an die Sitzung. Das ist nützlich, wenn derselbe Handler für mehrere Sitzungen registriert ist oder wenn Sie im Handler direkt Sitzungsdaten wie renderState oder visibilityState auslesen möchten.
Meist verwenden Sie die Eigenschaft zusammen mit eye, index, vertices und indices desselben Ereignisses. So können Sie die Maske der richtigen Sitzung und Ansicht zuordnen und anschließend zum Beispiel einen Stencil-Puffer füllen. Dann werden unsichtbare Pixel gar nicht erst gerendert, was Rechenzeit auf der GPU spart.
Rückgabewert
XRSession, auf der das Ereignis ausgelöst wurde. Der Wert ist schreibgeschützt und wird beim Erzeugen des Ereignisses festgelegt.Beispiele
Sitzung im visibilitymaskchange-Handler auslesen
const startXR = async () => {
const session = await navigator.xr.requestSession('immersive-vr');
session.addEventListener('visibilitymaskchange', (event) => {
// event.session ist dieselbe Sitzung wie oben
console.log(event.session === session);
console.log(`Neue Maske für Auge: ${event.eye}, Ansicht #${event.index}`);
console.log(`Sitzungsstatus: ${event.session.visibilityState}`);
});
};
document.querySelector('#vr-button').addEventListener('click', startXR);Ein Handler für mehrere Sitzungen mit Masken-Cache
// Masken je Sitzung und Ansicht speichern
const masksBySession = new WeakMap();
const onMaskChange = (event) => {
const { session, index, vertices, indices } = event;
if (!masksBySession.has(session)) {
masksBySession.set(session, new Map());
}
masksBySession.get(session).set(index, {
vertices: new Float32Array(vertices),
indices: new Uint32Array(indices)
});
console.log(`Sitzung hat jetzt ${masksBySession.get(session).size} Maske(n)`);
};
const start = async (mode) => {
const session = await navigator.xr.requestSession(mode);
session.addEventListener('visibilitymaskchange', onMaskChange);
session.addEventListener('end', () => masksBySession.delete(session), { once: true });
return session;
};
document.querySelector('#vr-button').addEventListener('click', () => start('immersive-vr'));Alternative: on-Property und Funktionserkennung
const init = async () => {
if (!('XRVisibilityMaskChangeEvent' in window)) {
console.warn('Sichtbarkeitsmasken werden nicht unterstützt');
return;
}
const session = await navigator.xr.requestSession('immersive-vr');
session.onvisibilitymaskchange = (event) => {
// Handler abmelden, sobald die Sitzung endet
event.session.addEventListener('end', () => {
event.session.onvisibilitymaskchange = null;
}, { once: true });
console.log('Maske aktualisiert:', event.vertices.length / 2, 'Eckpunkte');
};
};
document.querySelector('#vr-button').addEventListener('click', init);// Wichtig · Fallstricke
- Experimentell:
XRVisibilityMaskChangeEventist bisher kaum verbreitet und nur in einzelnen Chromium-basierten Browsern auf passender XR-Hardware verfügbar. Prüfen Sie die Unterstützung vorher, z. B. mit'XRVisibilityMaskChangeEvent' in window. Rechnen Sie außerdem damit, dass das Ereignis nie ausgelöst wird. - Sicherer Kontext: WebXR funktioniert nur über HTTPS (oder
localhost). Sitzungen müssen durch eine Nutzeraktion wie einen Klick gestartet werden. - Schreibgeschützt: Eine Zuweisung an
event.sessionwird ignoriert (im Strict Mode wirft sie einenTypeError). - Beendete Sitzungen: Nach dem
end-Ereignis verweistsessionweiterhin auf das Objekt, die Sitzung ist aber nicht mehr nutzbar. Löschen Sie gecachte Masken dann, z. B. mit einerWeakMap, damit kein Speicherleck entsteht. - Kopieren Sie
verticesundindices, wenn Sie sie später noch brauchen, statt sich auf die Daten des Ereignisobjekts zu verlassen.