XRSession.environmentBlendMode — Eigenschaft · JavaScript-Referenz

Signatur

XRSession.environmentBlendMode

Beschreibung

Die Eigenschaft environmentBlendMode des XRSession-Interfaces zeigt an, wie das XR-Gerät die von deiner Anwendung gerenderten Bilder mit der realen Welt kombiniert. Den Wert bestimmen die Hardware und der Sitzungsmodus, nicht die Anwendung. Deshalb ist die Eigenschaft schreibgeschützt.

Mögliche Werte:

"opaque": Die gerenderten Bilder verdecken die Umgebung vollständig. Das ist typisch für VR-Headsets in einer "immersive-vr"-Sitzung.
"additive": Die Pixel werden zur realen Welt addiert. Das ist typisch für optisch durchsichtige AR-Brillen wie HoloLens oder Magic Leap. Schwarz erscheint dort durchsichtig, und dunkle Farben lassen sich nicht darstellen.
"alpha-blend": Die Bilder werden anhand ihres Alphakanals mit einem Kamerabild gemischt. Das ist typisch für Passthrough-AR auf Smartphones (ARCore) oder bei Passthrough-Headsets.

Die Eigenschaft wird vor allem gebraucht, um die Darstellung an das Gerät anzupassen. Zum Beispiel lässt man bei "opaque" eine Skybox oder einen Hintergrund rendern, während man bei "alpha-blend" transparent löscht, damit die Kamera sichtbar bleibt. Bei "additive" vermeidet man dunkle, flächige Inhalte, weil sie kaum sichtbar wären.

Rückgabewert

Typ

"opaque" | "additive" | "alpha-blend"

Beschreibung

Ein String aus dem Aufzählungstyp XREnvironmentBlendMode. Er beschreibt, wie die Bilder der Anwendung mit der realen Umgebung gemischt werden.

Beispiele

Mischmodus nach dem Start einer AR-Sitzung auslesen

const startAR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-ar'))) {
    console.log('Immersive AR wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-ar');
  console.log('Mischmodus:', session.environmentBlendMode);
  return session;
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#ar-button').addEventListener('click', startAR);

Mischmodus: alpha-blend

Hintergrund abhängig vom Mischmodus rendern (WebGL)

const setupRendering = async (session, gl) => {
  await gl.makeXRCompatible();
  session.updateRenderState({ baseLayer: new XRWebGLLayer(session, gl) });

  // Bei VR mit dunklem Hintergrund löschen, bei AR transparent,
  // damit die reale Welt sichtbar bleibt
  const isOpaque = session.environmentBlendMode === 'opaque';
  const clearColor = isOpaque ? [0.1, 0.1, 0.15, 1.0] : [0, 0, 0, 0];

  const refSpace = await session.requestReferenceSpace('local');

  const onFrame = (time, frame) => {
    session.requestAnimationFrame(onFrame);
    const layer = session.renderState.baseLayer;
    gl.bindFramebuffer(gl.FRAMEBUFFER, layer.framebuffer);
    gl.clearColor(...clearColor);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
    if (isOpaque) {
      // hier z. B. eine Skybox zeichnen
    }
    // ... Szene für frame.getViewerPose(refSpace) zeichnen
  };
  session.requestAnimationFrame(onFrame);
};

Farben für additive Displays anpassen

const getUiTheme = (session) => {
  switch (session.environmentBlendMode) {
    case 'additive':
      // Schwarz wäre unsichtbar, darum helle, kräftige Farben
      return { panel: '#3af', text: '#fff', useDarkBackground: false };
    case 'alpha-blend':
      return { panel: 'rgba(0,0,0,0.6)', text: '#fff', useDarkBackground: true };
    case 'opaque':
    default:
      return { panel: '#222', text: '#eee', useDarkBackground: true };
  }
};

console.log(getUiTheme({ environmentBlendMode: 'additive' }));

{ panel: '#3af', text: '#fff', useDarkBackground: false }

// Wichtig · Fallstricke

Schreibgeschützt: Du kannst den Mischmodus nicht setzen oder anfordern. Er ergibt sich aus dem Gerät und dem Sitzungsmodus. Eine Zuweisung wird stillschweigend ignoriert, im Strict-Modus wirft sie einen TypeError.
Nicht aus dem Modus ableiten: Eine "immersive-ar"-Sitzung kann je nach Hardware "additive" oder "alpha-blend" liefern. Frage deshalb immer die Eigenschaft ab und verlasse dich nicht auf den Modus.
Inline-Sitzungen: Bei "inline"-Sitzungen ist der Wert immer "opaque".
Additive Displays: Schwarz und dunkle Töne erscheinen durchsichtig. Schatten und dunkle Texte sind dort kaum sichtbar.
Unterstützung: Die Eigenschaft gehört zum WebXR Augmented Reality Module. Sie ist in Chromium-basierten Browsern (Chrome für Android, Edge) und im Meta Quest Browser verfügbar, nicht in Firefox und Safari. WebXR braucht einen sicheren Kontext (HTTPS), und Sitzungen müssen durch eine Nutzeraktion gestartet werden.
Die verwandte Eigenschaft XRSession.interactionMode gibt an, ob die Oberfläche im Bildschirm- oder im Weltraum angezeigt wird. Sie ist unabhängig vom Mischmodus.

Siehe auch

XRSession XRSystem.requestSession() XRSystem.isSessionSupported() XRSession.interactionMode XRWebGLLayer XRSession.updateRenderState() XRSession.enabledFeatures