new XRLayerEvent() — Methode · JavaScript-Referenz

Signatur

new XRLayerEvent(type, options)

Beschreibung

Der Konstruktor XRLayerEvent() erzeugt ein Ereignisobjekt der WebXR Layers API. Solche Ereignisse beziehen sich immer auf eine bestimmte Ebene (XRLayer), zum Beispiel eine XRQuadLayer, XRCylinderLayer oder XREquirectLayer. Der wichtigste Anwendungsfall ist das Ereignis redraw: Der Browser löst es auf einer Kompositionsebene aus, wenn deren Inhalt verloren gegangen ist und die Anwendung ihn neu zeichnen muss.

Im normalen Betrieb musst du diesen Konstruktor fast nie selbst aufrufen, denn der User Agent erzeugt die Ereignisse automatisch. Sinnvoll ist der Aufruf vor allem für Tests, Polyfills oder wenn du deine Redraw-Logik gezielt von Hand auslösen willst, z. B. nach einem Wechsel der Textur.

Anders als bei vielen anderen Ereignis-Konstruktoren ist das Wörterbuch options hier Pflicht, weil es die Eigenschaft layer enthalten muss. Die Ebene steht danach über die schreibgeschützte Eigenschaft XRLayerEvent.layer zur Verfügung.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Name des Ereignisses, Groß-/Kleinschreibung wird beachtet. In der Spezifikation ist derzeit nur `"redraw"` vorgesehen.
$options Pflicht	object	Wörterbuch vom Typ `XRLayerEventInit`. Erbt von `EventInit` die Felder `bubbles`, `cancelable` und `composed` (jeweils Standard `false`).
$options.layer Pflicht	XRLayer	Die Ebene, auf die sich das Ereignis bezieht. Fehlt sie, wirft der Konstruktor einen `TypeError`.

Rückgabewert

Typ

XRLayerEvent

Beschreibung

Ein neues XRLayerEvent-Objekt, dessen Eigenschaft layer auf die übergebene Ebene verweist.

Beispiele

Auf das redraw-Ereignis einer Quad-Ebene reagieren

// Voraussetzung: immersive Sitzung mit dem Feature "layers"
const session = await navigator.xr.requestSession('immersive-vr', {
  requiredFeatures: ['layers']
});
const gl = document.createElement('canvas').getContext('webgl2', { xrCompatible: true });
const refSpace = await session.requestReferenceSpace('local');
const binding = new XRWebGLBinding(session, gl);

const quadLayer = binding.createQuadLayer({
  space: refSpace,
  viewPixelWidth: 1024,
  viewPixelHeight: 512,
  isStatic: true
});

const drawContent = (layer) => {
  // Inhalt der Ebene neu zeichnen (z. B. Textur hochladen)
  console.log('Ebene wird neu gezeichnet:', layer.constructor.name);
};

quadLayer.addEventListener('redraw', (event) => {
  drawContent(event.layer);
});

session.updateRenderState({ layers: [quadLayer] });

Ebene wird neu gezeichnet: XRQuadLayer

Redraw manuell auslösen (z. B. nach Texturwechsel oder im Test)

// quadLayer stammt aus einer laufenden WebXR-Layers-Sitzung
const event = new XRLayerEvent('redraw', { layer: quadLayer });

console.log(event.type);                  // Ereignisname
console.log(event.layer === quadLayer);   // Referenz auf die Ebene

quadLayer.dispatchEvent(event);

redraw true

Feature-Erkennung und Fehlerfall ohne layer

if (typeof XRLayerEvent === 'undefined') {
  console.log('WebXR Layers API wird nicht unterstützt');
} else {
  try {
    // options.layer ist Pflicht
    new XRLayerEvent('redraw', {});
  } catch (err) {
    console.log(err.name);
  }
}

TypeError

// Wichtig · Fallstricke

Experimentell: Die WebXR Layers API ist nicht Baseline. Unterstützt wird sie vor allem vom Meta Quest Browser (Chromium-basiert). Desktop-Browser wie Firefox und Safari kennen XRLayerEvent nicht. Prüfe deshalb immer mit typeof XRLayerEvent !== 'undefined', ob die Schnittstelle vorhanden ist, und fordere bei der Sitzung das Feature 'layers' an.
Sicherer Kontext: WebXR steht nur über HTTPS (bzw. localhost) zur Verfügung. Innerhalb von iframes braucht es außerdem die Berechtigungsrichtlinie xr-spatial-tracking.
Das Argument options mit einer gültigen layer ist Pflicht. Ohne sie wirft der Konstruktor einen TypeError. Die Eigenschaft layer ist schreibgeschützt.
Ein selbst erzeugtes und per dispatchEvent() ausgelöstes Ereignis hat isTrusted === false. Es ruft nur deine eigenen Listener auf und stellt keine vom Browser verworfenen Ebeneninhalte wieder her.
Das redraw-Ereignis ist vor allem bei statischen Ebenen (isStatic: true) wichtig: Wenn du es ignorierst, bleibt die Ebene nach einem Inhaltsverlust leer.

Siehe auch

XRLayerEvent XRLayerEvent.layer XRLayer XRWebGLBinding Event new CustomEvent()