XRCompositionLayer.destroy() — Methode · JavaScript-Referenz

Signatur

XRCompositionLayer.prototype.destroy()

Beschreibung

Die Methode destroy() der Schnittstelle XRCompositionLayer löst die Verbindung zwischen einer Ebene und ihren Ressourcen in der Grafikbibliothek, also z. B. den WebGL-Farb- und Tiefentexturen, die über XRWebGLBinding angelegt wurden. So kann der Browser den Grafikspeicher der Ebene freigeben, ohne auf die Speicherbereinigung (Garbage Collector) warten zu müssen.

Sinnvoll ist der Aufruf, wenn eine Ebene dauerhaft nicht mehr gebraucht wird. Typische Fälle:

Eine Quad-, Zylinder- oder Würfel-Ebene (XRQuadLayer, XRCylinderLayer, XRCubeLayer) für ein Menü oder Video wird geschlossen.
Eine Ebene wird durch eine neue mit anderer Auflösung oder anderem Texturformat ersetzt.
Die Anwendung räumt beim Ende einer XRSession auf.

Die Methode wirkt nur auf die Ebene selbst. Sie nimmt die Ebene nicht automatisch aus dem Render-Zustand der Sitzung heraus. Deshalb solltest du die Ebene vorher mit XRSession.updateRenderState({ layers: [...] }) aus der Liste der Ebenen entfernen. Danach rufst du destroy() auf.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Menü-Ebene schließen und Ressourcen freigeben

// Voraussetzung: session (XRSession mit Feature 'layers'), gl (WebGL2-Kontext), refSpace
const binding = new XRWebGLBinding(session, gl);

const projectionLayer = binding.createProjectionLayer({ textureType: 'texture' });
const menuLayer = binding.createQuadLayer({
  space: refSpace,
  viewPixelWidth: 1024,
  viewPixelHeight: 512,
  layout: 'mono'
});

session.updateRenderState({ layers: [menuLayer, projectionLayer] });

const closeMenu = () => {
  // 1. Ebene aus dem Render-Zustand entfernen
  session.updateRenderState({ layers: [projectionLayer] });
  // 2. Grafikressourcen freigeben
  menuLayer.destroy();
  console.log('Menü-Ebene zerstört');
};

closeMenu();

Menü-Ebene zerstört

Ebene durch eine neue mit höherer Auflösung ersetzen

let videoLayer = binding.createQuadLayer({
  space: refSpace,
  viewPixelWidth: 1280,
  viewPixelHeight: 720
});
session.updateRenderState({ layers: [videoLayer, projectionLayer] });

const upgradeResolution = () => {
  const oldLayer = videoLayer;
  videoLayer = binding.createQuadLayer({
    space: refSpace,
    viewPixelWidth: 1920,
    viewPixelHeight: 1080
  });
  // Neue Ebene einsetzen, dann die alte freigeben
  session.updateRenderState({ layers: [videoLayer, projectionLayer] });
  oldLayer.destroy();
};

upgradeResolution();

Aufräumen am Ende der XR-Sitzung

const activeLayers = new Set();

const createLayer = (options) => {
  const layer = binding.createQuadLayer(options);
  activeLayers.add(layer);
  return layer;
};

session.addEventListener('end', () => {
  for (const layer of activeLayers) {
    layer.destroy();
  }
  console.log(`${activeLayers.size} Ebenen freigegeben`);
  activeLayers.clear();
});

2 Ebenen freigegeben

// Wichtig · Fallstricke

Kompatibilität: Die WebXR Layers API ist experimentell. Sie funktioniert vor allem in Chromium-basierten XR-Browsern wie dem Meta Quest Browser. Desktop-Firefox und Safari unterstützen sie nicht. Die Sitzung muss mit requiredFeatures oder optionalFeatures: ['layers'] angefordert werden. Außerdem ist ein sicherer Kontext (HTTPS) nötig. Prüfe vorher, ob die API vorhanden ist, z. B. mit 'XRWebGLBinding' in window.

Nach destroy() ist die Ebene nicht mehr nutzbar. Aufrufe wie XRWebGLBinding.getSubImage() oder getViewSubImage() für diese Ebene schlagen fehl. Ein zerstörtes Objekt kann nicht wiederhergestellt werden, du musst eine neue Ebene erzeugen.
Entferne die Ebene zuerst mit updateRenderState() aus session.renderState.layers. Sonst verweist der Render-Zustand weiter auf eine Ebene ohne gültige Texturen.
Die zugehörigen WebGL-Texturen gehören dem Browser. Gib sie nicht selbst mit gl.deleteTexture() frei. Dafür ist destroy() da.
Bei Ebenen mit hoher Auflösung, etwa Video-Ebenen, spart ein früher Aufruf von destroy() spürbar Grafikspeicher. Das ist vor allem auf eigenständigen Headsets mit wenig Speicher wichtig.

Siehe auch

WorkerLocation.toString() CloseWatcher.destroy() Translator.destroy() Summarizer.destroy() new CompositionEvent()