WebGLRenderingContext.getBufferParameter() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.getBufferParameter(target, pname)

Beschreibung

Mit getBufferParameter() fragst du Eigenschaften des Buffers ab, der gerade an einem Bindungsziel wie gl.ARRAY_BUFFER oder gl.ELEMENT_ARRAY_BUFFER hängt. Du übergibst also kein Buffer-Objekt. Die Methode liest immer den Buffer, den du vorher mit gl.bindBuffer() gebunden hast.

Abfragen lassen sich zwei Werte:

gl.BUFFER_SIZE: die Größe des Datenspeichers in Bytes, wie sie mit bufferData() angelegt wurde.
gl.BUFFER_USAGE: der Nutzungshinweis, also gl.STATIC_DRAW, gl.DYNAMIC_DRAW oder gl.STREAM_DRAW (in WebGL 2 zusätzlich die Varianten *_READ und *_COPY).

Die Methode eignet sich zum Debuggen, für Prüfungen vor bufferSubData() (passt der neue Datenblock überhaupt in den Buffer?) und für Werkzeuge, die den GPU-Speicherverbrauch anzeigen. In WebGL2RenderingContext gibt es weitere Bindungsziele, zum Beispiel gl.UNIFORM_BUFFER, gl.COPY_READ_BUFFER, gl.COPY_WRITE_BUFFER, gl.TRANSFORM_FEEDBACK_BUFFER, gl.PIXEL_PACK_BUFFER und gl.PIXEL_UNPACK_BUFFER.

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	GLenum		Das Bindungsziel: `gl.ARRAY_BUFFER` oder `gl.ELEMENT_ARRAY_BUFFER`. In WebGL 2 zusätzlich `gl.COPY_READ_BUFFER`, `gl.COPY_WRITE_BUFFER`, `gl.TRANSFORM_FEEDBACK_BUFFER`, `gl.UNIFORM_BUFFER`, `gl.PIXEL_PACK_BUFFER` und `gl.PIXEL_UNPACK_BUFFER`.
$pname Pflicht	GLenum		Die abgefragte Eigenschaft: `gl.BUFFER_SIZE` oder `gl.BUFFER_USAGE`.

Rückgabewert

Typ

GLint | GLenum | null

Beschreibung

Bei gl.BUFFER_SIZE eine Zahl (GLint) mit der Größe in Bytes. Bei gl.BUFFER_USAGE ein GLenum mit dem Nutzungshinweis. Ist kein Buffer gebunden oder sind die Argumente ungültig, kommt null zurück und ein WebGL-Fehler wird gesetzt.

Beispiele

Größe und Nutzung eines Vertex-Buffers abfragen

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');

const vertices = new Float32Array([
  0.0,  0.5,
 -0.5, -0.5,
  0.5, -0.5
]);

const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);

const size = gl.getBufferParameter(gl.ARRAY_BUFFER, gl.BUFFER_SIZE);
const usage = gl.getBufferParameter(gl.ARRAY_BUFFER, gl.BUFFER_USAGE);

console.log('Größe:', size, 'Bytes');
console.log('STATIC_DRAW?', usage === gl.STATIC_DRAW);

Größe: 24 Bytes STATIC_DRAW? true

Vor bufferSubData() prüfen, ob die Daten passen

const gl = document.createElement('canvas').getContext('webgl');

const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
// 1024 Bytes reservieren, Daten folgen später
gl.bufferData(gl.ARRAY_BUFFER, 1024, gl.DYNAMIC_DRAW);

const safeUpdate = (offset, data) => {
  const capacity = gl.getBufferParameter(gl.ARRAY_BUFFER, gl.BUFFER_SIZE);
  if (offset + data.byteLength > capacity) {
    console.warn(`Überlauf: ${offset + data.byteLength} > ${capacity}`);
    return false;
  }
  gl.bufferSubData(gl.ARRAY_BUFFER, offset, data);
  return true;
};

console.log(safeUpdate(0, new Float32Array(128)));   // 512 Bytes
console.log(safeUpdate(768, new Float32Array(128))); // 768 + 512 > 1024

true Überlauf: 1280 > 1024 false

Nutzungshinweis lesbar ausgeben (Debug-Helfer)

const gl = document.createElement('canvas').getContext('webgl');

const usageName = (value) => ({
  [gl.STATIC_DRAW]: 'STATIC_DRAW',
  [gl.DYNAMIC_DRAW]: 'DYNAMIC_DRAW',
  [gl.STREAM_DRAW]: 'STREAM_DRAW'
})[value] ?? `unbekannt (${value})`;

const indexBuffer = gl.createBuffer();
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, new Uint16Array([0, 1, 2, 2, 3, 0]), gl.STREAM_DRAW);

const info = {
  size: gl.getBufferParameter(gl.ELEMENT_ARRAY_BUFFER, gl.BUFFER_SIZE),
  usage: usageName(gl.getBufferParameter(gl.ELEMENT_ARRAY_BUFFER, gl.BUFFER_USAGE))
};
console.log(info);

{ size: 12, usage: 'STREAM_DRAW' }

// Wichtig · Fallstricke

Bindung beachten: Die Methode liest immer den aktuell gebundenen Buffer am angegebenen Ziel. Wenn du den falschen Buffer gebunden hast oder keinen, bekommst du falsche Werte oder null. Bei null wird zusätzlich gl.INVALID_OPERATION gesetzt, abrufbar mit gl.getError().
Ungültige Argumente: Ein unbekanntes target oder pname setzt gl.INVALID_ENUM. WebGL-2-Ziele wie gl.UNIFORM_BUFFER funktionieren nur in einem webgl2-Kontext.
Performance: get*-Abfragen können die Pipeline zwischen CPU und GPU anhalten, bis die Werte vorliegen. Im Render-Loop solltest du sie meiden und die Buffer-Größe lieber selbst in JavaScript speichern.
Buffer-Inhalt: Die Methode liefert nur Metadaten, nie die Daten selbst. Um den Inhalt zu lesen, gibt es in WebGL 2 getBufferSubData().
Kompatibilität: Wird in allen modernen Browsern unterstützt, auch in WebGL2RenderingContext und OffscreenCanvas-Kontexten.

Siehe auch

WebGLRenderingContext.bindBuffer() WebGLRenderingContext.bufferData() WebGLRenderingContext.bufferSubData() WebGLRenderingContext.createBuffer() WebGLRenderingContext.getParameter() WebGL2RenderingContext.getBufferSubData() WebGLBuffer