WebGLRenderingContext.bindRenderbuffer() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.bindRenderbuffer(target, renderbuffer)

Beschreibung

Die Methode bindRenderbuffer() legt fest, welcher Renderbuffer gerade aktiv ist. WebGL arbeitet wie OpenGL als Zustandsmaschine: Funktionen wie renderbufferStorage() oder getRenderbufferParameter() bekommen kein Renderbuffer-Objekt übergeben, sondern wirken immer auf den Renderbuffer, der aktuell an gl.RENDERBUFFER gebunden ist.

Renderbuffer sind Speicherbereiche für Bilddaten, die nicht als Textur ausgelesen werden müssen. Typischerweise dienen sie als Tiefen- (DEPTH_COMPONENT16), Stencil- (STENCIL_INDEX8) oder kombinierter Tiefen-/Stencil-Anhang (DEPTH_STENCIL) eines Framebuffers für Offscreen-Rendering, z. B. bei Post-Processing, Picking oder Schattenberechnung. In WebGL 2 kommen Multisample-Renderbuffer über renderbufferStorageMultisample() hinzu.

Der typische Ablauf: Renderbuffer mit createRenderbuffer() erzeugen, mit bindRenderbuffer() binden, Speicher mit renderbufferStorage() reservieren und schließlich mit framebufferRenderbuffer() an einen Framebuffer anhängen. Wird null übergeben, wird die aktuelle Bindung aufgehoben.

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	GLenum		Bindungsziel. Muss `gl.RENDERBUFFER` sein, sonst entsteht der Fehler `gl.INVALID_ENUM`.
$renderbuffer Pflicht	WebGLRenderbuffer \| null		Das zu bindende Renderbuffer-Objekt aus `gl.createRenderbuffer()`. `null` löst die aktuelle Bindung.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Fehler werden nur über gl.getError() gemeldet.

Beispiele

Tiefenpuffer für einen Offscreen-Framebuffer anlegen

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

// Farbtextur als Render-Ziel
const colorTex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, colorTex);
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);

// Tiefenpuffer als Renderbuffer
const depthRb = gl.createRenderbuffer();
gl.bindRenderbuffer(gl.RENDERBUFFER, depthRb);
gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT16, width, height);

// Framebuffer zusammensetzen
const fbo = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, colorTex, 0);
gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, depthRb);

const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
console.log(status === gl.FRAMEBUFFER_COMPLETE ? 'Framebuffer vollständig' : 'Fehler: ' + status);

// Bindungen aufräumen
gl.bindRenderbuffer(gl.RENDERBUFFER, null);
gl.bindFramebuffer(gl.FRAMEBUFFER, null);

Framebuffer vollständig

Parameter des gebundenen Renderbuffers abfragen

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

const rb = gl.createRenderbuffer();
gl.bindRenderbuffer(gl.RENDERBUFFER, rb);
gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_STENCIL, 256, 128);

// Abfragen wirken auf den aktuell gebundenen Renderbuffer
const w = gl.getRenderbufferParameter(gl.RENDERBUFFER, gl.RENDERBUFFER_WIDTH);
const h = gl.getRenderbufferParameter(gl.RENDERBUFFER, gl.RENDERBUFFER_HEIGHT);
console.log(`${w}x${h}`);
console.log(gl.getParameter(gl.RENDERBUFFER_BINDING) === rb);

256x128 true

Renderbuffer bei Größenänderung des Canvas neu dimensionieren

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

const resizeDepthBuffer = () => {
  canvas.width = canvas.clientWidth * devicePixelRatio;
  canvas.height = canvas.clientHeight * devicePixelRatio;
  gl.bindRenderbuffer(gl.RENDERBUFFER, depthRb);
  gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT16, canvas.width, canvas.height);
  gl.bindRenderbuffer(gl.RENDERBUFFER, null);
  console.log('Tiefenpuffer:', canvas.width, canvas.height);
};

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

Tiefenpuffer: <Breite> <Höhe>

// Wichtig · Fallstricke

Ein anderer target-Wert als gl.RENDERBUFFER erzeugt gl.INVALID_ENUM. WebGL wirft keine Exceptions – Fehler nur über gl.getError() prüfen.
Ein Renderbuffer, der mit deleteRenderbuffer() gelöscht wurde, darf nicht mehr gebunden werden (INVALID_OPERATION). Ebenso dürfen Objekte nicht zwischen verschiedenen WebGL-Kontexten geteilt werden.
Die Bindung ist globaler Kontextzustand: Hilfsfunktionen sollten nach getaner Arbeit null binden oder den vorherigen Zustand (gl.getParameter(gl.RENDERBUFFER_BINDING)) wiederherstellen, um schwer auffindbare Fehler zu vermeiden.
Renderbuffer lassen sich nicht in Shadern abtasten. Wird der Inhalt später als Textur benötigt (z. B. Tiefentextur für Schatten), stattdessen eine Textur verwenden (in WebGL 1 über die Erweiterung WEBGL_depth_texture).
Bei Kontextverlust (webglcontextlost) werden alle Renderbuffer ungültig und müssen nach webglcontextrestored neu erzeugt werden.
In WebGL 1 und WebGL 2 (WebGL2RenderingContext) in allen modernen Browsern verfügbar.

Siehe auch

WebGLRenderingContext.createRenderbuffer() WebGLRenderingContext.renderbufferStorage() WebGLRenderingContext.framebufferRenderbuffer() WebGLRenderingContext.deleteRenderbuffer() WebGLRenderingContext.bindFramebuffer() WebGLRenderbuffer