Signatur
WebGL2RenderingContext.prototype.clearBufferfv(buffer, drawBuffer, values, srcOffset) / clearBufferiv(buffer, drawBuffer, values, srcOffset) / clearBufferuiv(buffer, drawBuffer, values, srcOffset) / clearBufferfi(buffer, drawBuffer, depth, stencil)
Beschreibung
Die Methodenfamilie clearBuffer[fiuv]() ist das WebGL-2-Gegenstück zu gl.clear(), arbeitet aber pro Puffer und abhängig vom Datentyp. Während gl.clear() alle Farbanhänge gleichzeitig mit dem über clearColor() gesetzten Wert löscht, können Sie mit clearBuffer* jeden Draw-Buffer eines Framebuffers (z. B. bei Multiple Render Targets / Deferred Shading) einzeln und mit eigenem Wert zurücksetzen.
Welche Variante Sie brauchen, hängt vom internen Format des Ziels ab:
clearBufferfv– Gleitkomma- und normalisierte Farbpuffer (RGBA8,RGBA16F,RGBA32F…) sowie der Tiefenpuffer (gl.DEPTH).clearBufferiv– vorzeichenbehaftete Integer-Farbpuffer (RGBA8I,R32I…) sowie der Stencil-Puffer (gl.STENCIL).clearBufferuiv– vorzeichenlose Integer-Farbpuffer (RGBA8UI,R32UI…).clearBufferfi– Tiefen- und Stencil-Puffer gleichzeitig (gl.DEPTH_STENCIL).
Integer-Farbanhänge lassen sich nur über clearBufferiv/clearBufferuiv sinnvoll löschen – gl.clear() liefert dort undefinierte Ergebnisse. Die Löschung berücksichtigt wie gl.clear() den Scissor-Test sowie die Schreibmasken (colorMask, depthMask, stencilMask), ignoriert aber die mit clearColor, clearDepth und clearStencil gesetzten Werte.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $buffer Pflicht | GLenum | Zu löschender Puffer: gl.COLOR, gl.DEPTH (nur fv), gl.STENCIL (nur iv) oder gl.DEPTH_STENCIL (nur fi). |
|
| $drawBuffer Pflicht | GLint | Bei gl.COLOR der Index des Draw-Buffers (entspricht der Position in gl.drawBuffers(), nicht direkt COLOR_ATTACHMENTi). Bei Tiefe/Stencil muss der Wert 0 sein. |
|
| $values Pflicht | Float32Array|Int32Array|Uint32Array|number[] | Nur fv/iv/uiv: Löschwerte. Für gl.COLOR vier Komponenten (RGBA), für gl.DEPTH/gl.STENCIL ein Wert. |
|
| $srcOffset | GLuint | 0 | Nur fv/iv/uiv: Startindex innerhalb von values. |
| $depth Pflicht | GLfloat | Nur clearBufferfi: Tiefenwert, wird auf [0, 1] begrenzt (üblich: 1.0). |
|
| $stencil Pflicht | GLint | Nur clearBufferfi: Stencil-Wert (üblich: 0). |
Beispiele
Standard-Framebuffer löschen (Farbe + Tiefe/Stencil)
const canvas = document.querySelector('canvas');
const gl = canvas.getContext('webgl2', { stencil: true });
// Ersetzt clearColor()+clearDepth()+clearStencil()+clear()
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.clearBufferfv(gl.COLOR, 0, [0.1, 0.1, 0.15, 1.0]);
gl.clearBufferfi(gl.DEPTH_STENCIL, 0, 1.0, 0);
console.log(gl.getError() === gl.NO_ERROR);true
G-Buffer mit gemischten Formaten (MRT) einzeln löschen
const gl = document.createElement('canvas').getContext('webgl2');
const w = 256, h = 256;
const makeTex = (internalFormat) => {
const tex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, tex);
gl.texStorage2D(gl.TEXTURE_2D, 1, internalFormat, w, h);
return tex;
};
const albedo = makeTex(gl.RGBA8); // normalisiert -> fv
const objectId = makeTex(gl.R32UI); // unsigned int -> uiv
const fbo = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, albedo, 0);
gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, objectId, 0);
gl.drawBuffers([gl.COLOR_ATTACHMENT0, gl.COLOR_ATTACHMENT1]);
// Jeder Draw-Buffer bekommt seinen eigenen, typgerechten Wert
gl.clearBufferfv(gl.COLOR, 0, new Float32Array([0, 0, 0, 1]));
gl.clearBufferuiv(gl.COLOR, 1, new Uint32Array([0xFFFFFFFF, 0, 0, 0])); // "kein Objekt"
console.log(gl.getError() === gl.NO_ERROR);true
Nur den Stencil-Puffer zurücksetzen und srcOffset nutzen
const gl = document.querySelector('canvas').getContext('webgl2', { stencil: true });
// Mehrere Presets in einem Array, per srcOffset auswählen
const presets = new Float32Array([
1, 1, 1, 1, // Weiß (Offset 0)
0, 0, 0, 1 // Schwarz (Offset 4)
]);
const darkMode = window.matchMedia('(prefers-color-scheme: dark)').matches;
gl.clearBufferfv(gl.COLOR, 0, presets, darkMode ? 4 : 0);
// Stencil-Maske für den nächsten Pass zurücksetzen, Tiefe bleibt erhalten
gl.stencilMask(0xFF);
gl.clearBufferiv(gl.STENCIL, 0, new Int32Array([0]));