OES_draw_buffers_indexed.blendEquationiOES() — Methode · JavaScript-Referenz

Signatur

OES_draw_buffers_indexed.prototype.blendEquationiOES(buf, mode)

Beschreibung

blendEquationiOES() ist die indizierte Variante von WebGL2RenderingContext.blendEquation(). Sie gehört zur WebGL-2-Erweiterung OES_draw_buffers_indexed, die Blending-Zustände pro Zeichenpuffer erlaubt. Die Methode setzt die Mischgleichung für RGB und Alpha gleichzeitig, aber nur für den Puffer mit dem Index buf.

Das ist vor allem beim Multiple Render Targets (MRT)-Rendering nützlich, etwa in Deferred-Shading- oder Order-Independent-Transparency-Verfahren: In einen Farbanhang wird additiv akkumuliert (gl.FUNC_ADD), während ein anderer z. B. per gl.MIN oder gl.MAX den kleinsten bzw. größten Wert speichert. Ohne diese Erweiterung gilt eine Mischgleichung immer für alle Anhänge gleichzeitig.

Damit Blending überhaupt wirkt, muss es aktiviert sein – global über gl.enable(gl.BLEND) oder gezielt pro Puffer über ext.enableiOES(gl.BLEND, buf). Sollen RGB und Alpha unterschiedliche Gleichungen erhalten, verwendet man stattdessen blendEquationSeparateiOES().

Parameter

Name	Typ	Default	Beschreibung
$buf Pflicht	number (GLuint)		Index des Zeichenpuffers, für den die Gleichung gilt (entspricht `gl.COLOR_ATTACHMENT0 + buf` bzw. dem Eintrag in `gl.drawBuffers()`). Muss kleiner als `gl.getParameter(gl.MAX_DRAW_BUFFERS)` sein.
$mode Pflicht	GLenum		Mischgleichung: `gl.FUNC_ADD`, `gl.FUNC_SUBTRACT`, `gl.FUNC_REVERSE_SUBTRACT`, `gl.MIN` oder `gl.MAX`.

Rückgabewert

Typ

void

Beschreibung

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

Beispiele

Erweiterung laden und Gleichung für Puffer 1 setzen

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2');
const ext = gl?.getExtension('OES_draw_buffers_indexed');

if (!ext) {
  console.log('OES_draw_buffers_indexed nicht verfügbar');
} else {
  ext.enableiOES(gl.BLEND, 1);
  ext.blendEquationiOES(1, gl.MAX);
  // Abfrage des gesetzten Zustands für Puffer 1
  const mode = gl.getIndexedParameter(gl.BLEND_EQUATION_RGB, 1);
  console.log(mode === gl.MAX);
}

true

MRT: additive Akkumulation und Minimum-Tiefe getrennt

const gl = document.querySelector('canvas').getContext('webgl2');
const ext = gl.getExtension('OES_draw_buffers_indexed');

// Framebuffer mit zwei Farbanhängen
const fb = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, fb);
const makeTex = (attachment) => {
  const tex = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, tex);
  gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, gl.canvas.width, gl.canvas.height);
  gl.framebufferTexture2D(gl.FRAMEBUFFER, attachment, gl.TEXTURE_2D, tex, 0);
  return tex;
};
makeTex(gl.COLOR_ATTACHMENT0);
makeTex(gl.COLOR_ATTACHMENT1);
gl.drawBuffers([gl.COLOR_ATTACHMENT0, gl.COLOR_ATTACHMENT1]);

gl.enable(gl.BLEND);
// Puffer 0: Farben aufsummieren
ext.blendEquationiOES(0, gl.FUNC_ADD);
ext.blendFunciOES(0, gl.ONE, gl.ONE);
// Puffer 1: kleinsten Wert behalten
ext.blendEquationiOES(1, gl.MIN);
ext.blendFunciOES(1, gl.ONE, gl.ONE);

// ... anschließend gl.drawArrays(...) mit einem Shader, der zwei Ausgaben schreibt

Zustand zurücksetzen

const resetBlendEquations = (gl, ext) => {
  const max = gl.getParameter(gl.MAX_DRAW_BUFFERS);
  for (let i = 0; i < max; i++) {
    ext.blendEquationiOES(i, gl.FUNC_ADD);
  }
};

const gl = document.createElement('canvas').getContext('webgl2');
const ext = gl.getExtension('OES_draw_buffers_indexed');
if (ext) {
  resetBlendEquations(gl, ext);
  console.log(gl.getError() === gl.NO_ERROR);
}

true

// Wichtig · Fallstricke

Nur WebGL 2: Die Erweiterung gibt es nicht für WebGL-1-Kontexte. Immer prüfen, ob getExtension() null liefert. Browser unterstützen sie unterschiedlich (Chromium ab etwa Version 100, sonst lückenhaft, stark abhängig von Treiber und GPU).
Ist buf größer oder gleich MAX_DRAW_BUFFERS, entsteht gl.INVALID_VALUE; ein ungültiger mode erzeugt gl.INVALID_ENUM. Es wird keine Ausnahme geworfen, Fehler also mit gl.getError() prüfen.
Ein späterer Aufruf von gl.blendEquation() überschreibt die Gleichung für alle Puffer, auch die vorher indiziert gesetzten.
Bei gl.MIN und gl.MAX werden die Mischfaktoren aus blendFunc ignoriert.
Den aktuellen Wert pro Puffer fragt man mit gl.getIndexedParameter(gl.BLEND_EQUATION_RGB, i) bzw. gl.BLEND_EQUATION_ALPHA ab.

Siehe auch

OES_draw_buffers_indexed OES_draw_buffers_indexed.blendEquationSeparateiOES() OES_draw_buffers_indexed.blendFunciOES() OES_draw_buffers_indexed.enableiOES() WebGLRenderingContext.blendEquation() WebGL2RenderingContext.drawBuffers()