XRCompositionLayer.blendTextureSourceAlpha — Eigenschaft · JavaScript-Referenz

Signatur

XRCompositionLayer.blendTextureSourceAlpha

Beschreibung

Die Eigenschaft blendTextureSourceAlpha der Schnittstelle XRCompositionLayer steuert, wie der XR-Compositor die Textur eines Layers mit den darunterliegenden Layern verrechnet. Ist sie true, wird der Alpha-Kanal der Textur verwendet: Transparente oder halbtransparente Pixel lassen die darunterliegenden Layer (bzw. bei AR die reale Umgebung) durchscheinen. Ist sie false, wird der Alpha-Kanal ignoriert und jedes Pixel als vollständig deckend behandelt.

Die Eigenschaft ist les- und schreibbar und wird von allen abgeleiteten Layer-Typen geerbt, etwa XRProjectionLayer, XRQuadLayer, XRCylinderLayer, XREquirectLayer und XRCubeLayer. Änderungen wirken sich ab dem nächsten Frame aus – man kann sie also zur Laufzeit umschalten, ohne den Layer neu zu erzeugen.

Typische Einsatzfälle: UI-Panels mit abgerundeten Ecken oder transparentem Hintergrund als Quad-Layer (Alpha an), oder ein Video-/Hintergrund-Layer, der ohnehin vollflächig deckt (Alpha aus). Das Abschalten spart dem Compositor Arbeit und verhindert unerwünschte Transparenz, wenn der Renderer versehentlich Alpha-Werte kleiner 1 schreibt.

Beispiele

Transparentes UI-Panel als Quad-Layer

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2', { xrCompatible: true });

const session = await navigator.xr.requestSession('immersive-vr', {
  requiredFeatures: ['layers']
});
const refSpace = await session.requestReferenceSpace('local');
const binding = new XRWebGLBinding(session, gl);

const projLayer = binding.createProjectionLayer({ textureType: 'texture' });
const uiLayer = binding.createQuadLayer({
  space: refSpace,
  viewPixelWidth: 1024,
  viewPixelHeight: 512,
  layout: 'mono',
  transform: new XRRigidTransform({ x: 0, y: 1.5, z: -1.5 })
});

// Panel mit transparentem Hintergrund: Alpha berücksichtigen
uiLayer.blendTextureSourceAlpha = true;

session.updateRenderState({ layers: [projLayer, uiLayer] });
console.log(uiLayer.blendTextureSourceAlpha);

true

Deckenden Hintergrund-Layer ohne Alpha rendern

// Annahme: session, binding und refSpace existieren bereits
const skyLayer = binding.createEquirectLayer({
  space: refSpace,
  viewPixelWidth: 4096,
  viewPixelHeight: 2048,
  layout: 'mono'
});

// Panorama deckt vollständig – Alpha ignorieren
skyLayer.blendTextureSourceAlpha = false;

session.updateRenderState({ layers: [skyLayer, projLayer] });

Transparenz zur Laufzeit umschalten

// Button im 3D-Menü schaltet Durchsichtigkeit des Panels um
const toggleTransparency = (layer) => {
  layer.blendTextureSourceAlpha = !layer.blendTextureSourceAlpha;
  console.log(`Alpha-Blending: ${layer.blendTextureSourceAlpha ? 'an' : 'aus'}`);
};

toggleTransparency(uiLayer);

Alpha-Blending: aus

// Wichtig · Fallstricke

Experimentell: Die WebXR Layers API wird bisher nur von wenigen Browsern unterstützt (vor allem Meta Quest Browser). Vorher per 'XRWebGLBinding' in window prüfen und das Feature 'layers' beim Sessionstart anfordern. Nur in sicheren Kontexten (HTTPS) verfügbar.
Vormultipliziertes Alpha: Der Compositor erwartet Texturen mit vormultipliziertem Alpha. Schreibt der Renderer nicht vormultiplizierte Farben, entstehen helle Ränder oder falsche Farben an halbtransparenten Kanten.
Bei false werden auch unabsichtlich transparente Pixel deckend dargestellt – nicht gelöschte Bereiche der Textur erscheinen dann schwarz bzw. mit altem Inhalt.
Die Reihenfolge der Layer im layers-Array von updateRenderState() bestimmt, womit überblendet wird: Spätere Layer liegen oben.
Deckende Layer (false) können auf manchen Geräten effizienter komponiert werden – bei großen Hintergrund-Layern lohnt sich das Abschalten.

Siehe auch

XRCompositionLayer XRWebGLBinding XRWebGLBinding.createQuadLayer() XRProjectionLayer XRQuadLayer XRSession.updateRenderState()