XRWebGLLayer.framebufferHeight — Eigenschaft · JavaScript-Referenz

Signatur

XRWebGLLayer.framebufferHeight

Beschreibung

framebufferHeight gibt die Höhe des Framebuffers in Pixeln zurück, den eine XRWebGLLayer für das Rendern einer WebXR-Sitzung bereitstellt. Zusammen mit framebufferWidth beschreibt sie die tatsächliche Größe der Zeichenfläche, in die alle Ansichten (z. B. linkes und rechtes Auge) gezeichnet werden.

Die Größe wird beim Erzeugen der Ebene vom Browser festgelegt. Sie hängt von der nativen Auflösung des Geräts und von der Option framebufferScaleFactor ab, die man dem Konstruktor new XRWebGLLayer(session, gl, options) übergibt. Ein Faktor unter 1.0 senkt die Auflösung und verbessert die Leistung, ein Faktor über 1.0 erhöht die Schärfe.

Im Alltag braucht man den Wert vor allem, um eigene Render-Ziele (Post-Processing-Texturen, Tiefenpuffer) passend anzulegen oder um Auflösung und Leistung zu protokollieren. Die Viewports der einzelnen Ansichten sollte man dagegen immer mit XRWebGLLayer.getViewport(view) ermitteln und nicht selbst aus Breite und Höhe ausrechnen.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl (unsigned long): die Höhe des Framebuffers in Pixeln. Der Wert ist schreibgeschützt.

Beispiele

Framebuffer-Größe nach dem Start der Sitzung protokollieren

const startXR = async () => {
  const canvas = document.createElement('canvas');
  const gl = canvas.getContext('webgl2', { xrCompatible: true });
  const session = await navigator.xr.requestSession('immersive-vr');

  const layer = new XRWebGLLayer(session, gl);
  await session.updateRenderState({ baseLayer: layer });

  console.log(`Framebuffer: ${layer.framebufferWidth} × ${layer.framebufferHeight} px`);
};

document.querySelector('#enter-vr').addEventListener('click', startXR);

Framebuffer: 3664 × 1920 px (geräteabhängig)

Auflösung per framebufferScaleFactor reduzieren

const createLayer = (session, gl) => {
  const nativeScale = XRWebGLLayer.getNativeFramebufferScaleFactor(session);
  const layer = new XRWebGLLayer(session, gl, {
    framebufferScaleFactor: 0.5 // halbe Auflösung für mehr Leistung
  });
  console.log('Nativer Faktor:', nativeScale);
  console.log('Höhe mit Faktor 0.5:', layer.framebufferHeight);
  return layer;
};

Nativer Faktor: 1 Höhe mit Faktor 0.5: 960

Passende Offscreen-Textur für Post-Processing anlegen

const createPostTarget = (gl, layer) => {
  const width = layer.framebufferWidth;
  const height = layer.framebufferHeight;

  const texture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, texture);
  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0,
    gl.RGBA, gl.UNSIGNED_BYTE, null);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);

  const fbo = gl.createFramebuffer();
  gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
  gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0,
    gl.TEXTURE_2D, texture, 0);

  return { fbo, texture, width, height };
};

// Wichtig · Fallstricke

Nicht für Viewports verwenden: Der Framebuffer enthält meist mehrere Ansichten nebeneinander. Die Bereiche pro Auge liefert layer.getViewport(view); ein gl.viewport(0, 0, width, framebufferHeight) würde über beide Augen zeichnen.
Der Browser darf den framebufferScaleFactor auf einen unterstützten Bereich begrenzen. Die tatsächliche Höhe kann daher vom erwarteten Wert abweichen – immer die Eigenschaft auslesen statt selbst zu rechnen.
Bei Sitzungen im Modus inline entspricht der Framebuffer der Canvas-Größe, und layer.framebuffer ist null (Standard-Framebuffer).
Der WebGL-Kontext muss mit xrCompatible: true erzeugt oder über gl.makeXRCompatible() vorbereitet werden, sonst wirft der Konstruktor einen Fehler.
Kompatibilität: WebXR gibt es nur in sicheren Kontexten (HTTPS) und vor allem in Chromium-basierten Browsern sowie Headset-Browsern. Firefox und Safari auf dem Desktop unterstützen es nicht; vorher 'xr' in navigator prüfen.

Siehe auch

XRWebGLLayer XRWebGLLayer.framebufferWidth XRWebGLLayer.framebuffer XRWebGLLayer.getViewport() XRWebGLLayer.getNativeFramebufferScaleFactor() XRSession.updateRenderState() XRWebGLLayer.fixedFoveation