WebGLRenderingContext.bindBuffer() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.bindBuffer(target, buffer)

Beschreibung

bindBuffer() legt fest, welcher Puffer gerade an einem bestimmten Bindungspunkt (Ziel) aktiv ist. WebGL arbeitet als Zustandsautomat: Methoden wie bufferData(), bufferSubData() oder vertexAttribPointer() bekommen keinen Puffer als Argument, sondern wirken immer auf den Puffer, der gerade am jeweiligen Ziel gebunden ist.

In WebGL 1 gibt es zwei Ziele:

gl.ARRAY_BUFFER – für Vertex-Attribute wie Positionen, Farben, Normalen oder Texturkoordinaten.
gl.ELEMENT_ARRAY_BUFFER – für Indexdaten, die mit drawElements() verwendet werden.

In WebGL2RenderingContext kommen weitere Ziele hinzu: COPY_READ_BUFFER, COPY_WRITE_BUFFER, TRANSFORM_FEEDBACK_BUFFER, UNIFORM_BUFFER, PIXEL_PACK_BUFFER und PIXEL_UNPACK_BUFFER.

Ein Puffer bekommt sein Ziel beim ersten Binden fest zugewiesen. Übergibt man null, wird die Bindung am Ziel aufgehoben. Wichtig: vertexAttribPointer() merkt sich den beim Aufruf gebundenen ARRAY_BUFFER, danach darf man einen anderen binden. Die ELEMENT_ARRAY_BUFFER-Bindung gehört dagegen zum aktuellen Vertex Array Object (VAO).

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	GLenum		Bindungspunkt: `gl.ARRAY_BUFFER` oder `gl.ELEMENT_ARRAY_BUFFER`. In WebGL 2 zusätzlich `COPY_READ_BUFFER`, `COPY_WRITE_BUFFER`, `TRANSFORM_FEEDBACK_BUFFER`, `UNIFORM_BUFFER`, `PIXEL_PACK_BUFFER` und `PIXEL_UNPACK_BUFFER`.
$buffer Pflicht	WebGLBuffer \| null		Der zu bindende Puffer (aus `gl.createBuffer()`) oder `null`, um die aktuelle Bindung aufzuheben.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Fehler meldet WebGL über gl.getError().

Beispiele

Vertex-Positionen hochladen und einem Attribut zuweisen

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

// Dreieck in Clip-Space-Koordinaten
const positions = new Float32Array([
   0.0,  0.5,
  -0.5, -0.5,
   0.5, -0.5,
]);

const positionBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer);
gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);

// program = zuvor gelinktes WebGLProgram mit Attribut "a_position"
const loc = gl.getAttribLocation(program, 'a_position');
gl.enableVertexAttribArray(loc);
// Verknüpft das Attribut mit dem aktuell gebundenen ARRAY_BUFFER
gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);

gl.drawArrays(gl.TRIANGLES, 0, 3);

Indexpuffer für ein Rechteck mit drawElements

const vertices = new Float32Array([
  -0.5,  0.5,   0.5,  0.5,
  -0.5, -0.5,   0.5, -0.5,
]);
const indices = new Uint16Array([0, 1, 2, 2, 1, 3]);

const vbo = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
gl.enableVertexAttribArray(loc);

const ibo = gl.createBuffer();
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);

gl.drawElements(gl.TRIANGLES, indices.length, gl.UNSIGNED_SHORT, 0);

Aktuelle Bindung abfragen und aufheben

const buf = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buf);
console.log(gl.getParameter(gl.ARRAY_BUFFER_BINDING) === buf);

// Bindung lösen
gl.bindBuffer(gl.ARRAY_BUFFER, null);
console.log(gl.getParameter(gl.ARRAY_BUFFER_BINDING));

true null

Falsches Ziel erzeugt INVALID_OPERATION

const buf = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buf);

// Derselbe Puffer an ein anderes Ziel – in WebGL nicht erlaubt
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, buf);
console.log(gl.getError() === gl.INVALID_OPERATION);

true

// Wichtig · Fallstricke

Festes Ziel: Anders als in OpenGL darf ein Puffer in WebGL nach dem ersten Binden nicht an ein anderes Ziel (z. B. von ARRAY_BUFFER nach ELEMENT_ARRAY_BUFFER) gebunden werden. Das erzeugt INVALID_OPERATION.
Ein ungültiges target führt zu INVALID_ENUM. Einen mit deleteBuffer() gelöschten Puffer zu binden, schlägt ebenfalls fehl.
Fehler werden nicht als Exception geworfen. Man findet sie nur mit gl.getError() oder mit Debug-Werkzeugen wie Spector.js.
bufferData() und vertexAttribPointer() ohne vorher gebundenen Puffer führen zu INVALID_OPERATION. Ein typischer Fehler ist, in einer Render-Schleife das erneute Binden zu vergessen, nachdem man an anderer Stelle einen anderen Puffer gebunden hat.
Die ELEMENT_ARRAY_BUFFER-Bindung gehört zum aktuell gebundenen VAO (WebGL 2 oder Erweiterung OES_vertex_array_object). Wer bindVertexArray(null) vergisst, verändert unbeabsichtigt den Zustand des VAO.
Performance: Häufiges Umbinden kostet Treiberzeit. Mit VAOs und verschachtelten (interleaved) Puffern lassen sich Zustandswechsel reduzieren.
Kompatibilität: WebGL 1 wird von allen modernen Browsern unterstützt. Die zusätzlichen Ziele gibt es nur in WebGL2RenderingContext.

Siehe auch

WebGLRenderingContext.createBuffer() WebGLRenderingContext.bufferData() WebGLRenderingContext.bufferSubData() WebGLRenderingContext.vertexAttribPointer() WebGLRenderingContext.deleteBuffer() WebGLRenderingContext.drawElements() WebGLBuffer WebGL2RenderingContext.bindBufferBase()