WebGLRenderingContext.drawingBufferWidth — Eigenschaft · JavaScript-Referenz

Signatur

WebGLRenderingContext.drawingBufferWidth

Beschreibung

drawingBufferWidth gibt die tatsächliche Breite des Zeichenpuffers (Drawing Buffer) eines WebGL-Kontexts in Pixeln zurück. Normalerweise entspricht der Wert dem Attribut width des zugehörigen <canvas>-Elements. Er kann aber kleiner ausfallen, wenn der Browser bzw. die Grafikhardware die angeforderte Größe nicht bereitstellen kann, etwa weil sie die maximale Viewport- oder Renderbuffer-Größe überschreitet.

Gebraucht wird die Eigenschaft vor allem, um gl.viewport() korrekt zu setzen, das Seitenverhältnis für Projektionsmatrizen zu berechnen und beim Auslesen mit gl.readPixels() die richtige Puffergröße anzulegen. Wer sich allein auf canvas.width verlässt, riskiert verzerrte oder abgeschnittene Darstellungen, falls der Puffer kleiner ist als angefordert.

Der Wert ist nicht mit der CSS-Anzeigegröße (clientWidth) gleichzusetzen. Auf hochauflösenden Displays setzt man canvas.width üblicherweise auf clientWidth * devicePixelRatio und liest danach drawingBufferWidth aus, um die wirklich zugewiesene Größe zu bekommen. Die Eigenschaft gibt es genauso auf WebGL2RenderingContext.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl (GLsizei) mit der tatsächlichen Breite des Zeichenpuffers in Pixeln. Ist der Kontext verloren gegangen, kann der Wert 0 sein.

Beispiele

Breite des Zeichenpuffers auslesen

const canvas = document.createElement('canvas');
canvas.width = 640;
canvas.height = 480;
const gl = canvas.getContext('webgl');

console.log(gl.drawingBufferWidth);  // tatsächliche Pufferbreite
console.log(gl.drawingBufferHeight);

640 480

Viewport und Seitenverhältnis bei Größenänderung anpassen

const canvas = document.querySelector('#scene');
const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');

const resize = () => {
  const dpr = window.devicePixelRatio || 1;
  canvas.width = Math.round(canvas.clientWidth * dpr);
  canvas.height = Math.round(canvas.clientHeight * dpr);

  // Immer die tatsächliche Puffergröße verwenden, nicht canvas.width
  const w = gl.drawingBufferWidth;
  const h = gl.drawingBufferHeight;
  gl.viewport(0, 0, w, h);

  const aspect = w / h;
  console.log(`Puffer: ${w}x${h}, Seitenverhältnis: ${aspect.toFixed(2)}`);
};

window.addEventListener('resize', resize);
resize();

Puffer: 1920x1080, Seitenverhältnis: 1.78

Pixel des gesamten Puffers mit readPixels auslesen

const gl = document.querySelector('canvas').getContext('webgl', {
  preserveDrawingBuffer: true
});

gl.clearColor(1, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);

const w = gl.drawingBufferWidth;
const h = gl.drawingBufferHeight;
const pixels = new Uint8Array(w * h * 4);
gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, pixels);

console.log(pixels.slice(0, 4));

Uint8Array(4) [255, 0, 0, 255]

Abweichung vom angeforderten Wert erkennen

const canvas = document.createElement('canvas');
canvas.width = 32768; // absichtlich sehr groß
canvas.height = 32768;
const gl = canvas.getContext('webgl');

if (gl.drawingBufferWidth !== canvas.width) {
  console.warn(`Angefordert: ${canvas.width}, erhalten: ${gl.drawingBufferWidth}`);
}

Angefordert: 32768, erhalten: 8192 (geräteabhängig)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an gl.drawingBufferWidth wird ignoriert bzw. löst im Strict Mode einen TypeError aus. Die Größe ändert man über canvas.width.
Nicht automatisch der Viewport: Ändert sich die Canvas-Größe, wird der Viewport nicht automatisch angepasst. Danach muss man gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight) selbst aufrufen.
Kann kleiner sein als angefordert: Das Limit hängt von Hardware und Treiber ab (vgl. gl.getParameter(gl.MAX_VIEWPORT_DIMS)). Dabei bleibt das Seitenverhältnis nicht zwingend exakt erhalten.
CSS-Größe ≠ Puffergröße: clientWidth und getBoundingClientRect() liefern CSS-Pixel, nicht die Pufferauflösung.
Ist der Kontext verloren (webglcontextlost), kann der Wert 0 sein.
Ab WebGL 2 lässt sich die Größe des Zeichenpuffers auch direkt über drawingBufferStorage() festlegen (bisher nur in einigen Browsern).
Kompatibilität: Unterstützen alle Browser mit WebGL, auch in OffscreenCanvas-Kontexten.

Siehe auch

WebGLRenderingContext.drawingBufferHeight WebGLRenderingContext.viewport() WebGLRenderingContext.readPixels() WebGLRenderingContext.canvas HTMLCanvasElement.width Window.devicePixelRatio WebGLRenderingContext