Signatur
Beschreibung
Die schreibgeschützte Eigenschaft index des XRVisibilityMaskChangeEvent enthält den Index der XRView, für die das XR-Gerät eine neue Sichtbarkeitsmaske meldet. Der Index bezieht sich auf die Reihenfolge im Array XRViewerPose.views, das du pro Frame über XRFrame.getViewerPose() erhältst.
Die Maske beschreibt, welcher Teil des Framebuffers einer Ansicht durch die Linsen des Headsets überhaupt sichtbar ist. Das Ereignis visibilitymaskchange wird an der XRSession ausgelöst und liefert in vertices und indices ein Dreiecksnetz des sichtbaren Bereichs. Mit index ordnest du dieses Netz der richtigen Ansicht zu. So kannst du z. B. einen Stencil- oder Tiefenpuffer vorbelegen und die Fragment-Shader-Arbeit für unsichtbare Pixel sparen.
Normalerweise speicherst du die Maske in einer Struktur, deren Schlüssel index ist, und greifst in der Render-Schleife mit demselben Index darauf zu, den du beim Durchlaufen von pose.views verwendest. Zusätzlich gibt eye an, ob es um das linke oder rechte Auge geht oder um keines von beiden.
Rückgabewert
unsigned long): die Position der betroffenen XRView in XRViewerPose.views.Beispiele
Masken pro Ansicht mit addEventListener speichern
const visibilityMasks = new Map();
const session = await navigator.xr.requestSession('immersive-vr');
session.addEventListener('visibilitymaskchange', (event) => {
// index ordnet die Maske der richtigen XRView zu
visibilityMasks.set(event.index, {
eye: event.eye,
vertices: event.vertices, // Float32Array (x, y, …)
indices: event.indices // Uint32Array (Dreiecke)
});
console.log(`Maske für View ${event.index} (${event.eye}) aktualisiert`);
});Maske in der Render-Schleife verwenden
const onXRFrame = (time, frame) => {
const session = frame.session;
session.requestAnimationFrame(onXRFrame);
const pose = frame.getViewerPose(refSpace);
if (!pose) return;
pose.views.forEach((view, i) => {
// Derselbe Index wie event.index
const mask = visibilityMasks.get(i);
if (mask) {
drawStencilMask(mask.vertices, mask.indices); // eigene WebGL-Hilfsfunktion
}
renderScene(view);
});
};Ereignis über die on-Property und per Konstruktor testen
session.onvisibilitymaskchange = (event) => {
console.log('Index:', event.index, 'Dreiecke:', event.indices.length / 3);
};
// Synthetisches Ereignis, z. B. für Unit-Tests
const testEvent = new XRVisibilityMaskChangeEvent('visibilitymaskchange', {
session,
eye: 'left',
index: 0,
vertices: new Float32Array([-1, -1, 1, -1, 0, 1]),
indices: new Uint32Array([0, 1, 2])
});
session.dispatchEvent(testEvent);// Wichtig · Fallstricke
- Experimentell: Die Visibility-Mask-API ist kein fester Teil der WebXR-Kernspezifikation und wird nur von einzelnen Chromium-basierten XR-Browsern unterstützt. Prüfe die Unterstützung vorab mit
'XRVisibilityMaskChangeEvent' in window. - Der Index gilt nur für die Ansichtsreihenfolge dieser Session. Die Zahl und Reihenfolge der Ansichten kann sich z. B. durch zusätzliche Ansichten (
secondary-views) ändern. Verlasse dich deshalb nicht auf „0 = links“, sondern prüfe zusätzlichevent.eye. - Das Ereignis kann während der Session mehrmals ausgelöst werden, etwa bei geänderter Linsen- oder IPD-Einstellung. Überschreibe dann die gespeicherte Maske, statt sie nur einmal beim Start zu lesen.
- Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert (im Strict Mode löst sie einen
TypeErroraus). - Voraussetzung ist ein sicherer Kontext (HTTPS).