WebGLRenderingContext.blendEquationSeparate() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.blendEquationSeparate(modeRGB, modeAlpha)

Beschreibung

blendEquationSeparate() bestimmt, wie die bereits mit den Blendfaktoren gewichteten Quell- und Zielwerte zusammengeführt werden. Anders als blendEquation(), das eine Gleichung für alle vier Kanäle setzt, kannst du hier für die Farbkanäle (RGB) und den Alpha-Kanal verschiedene Gleichungen wählen.

Die Gleichungen im Überblick (S = Quelle, D = Ziel, sF/dF = Blendfaktoren):

gl.FUNC_ADD: S·sF + D·dF (Standard)
gl.FUNC_SUBTRACT: S·sF − D·dF
gl.FUNC_REVERSE_SUBTRACT: D·dF − S·sF
gl.MIN / gl.MAX (WebGL 2 oder Erweiterung EXT_blend_minmax): komponentenweises Minimum bzw. Maximum von S und D; die Blendfaktoren werden dabei ignoriert.

Die Einstellung wirkt nur, wenn Blending mit gl.enable(gl.BLEND) aktiviert ist. Typische Anwendungsfälle sind Partikeleffekte, bei denen die Farbe additiv, der Alpha-Wert aber per Maximum erhalten bleiben soll, oder Offscreen-Framebuffer, deren Alpha-Kanal später noch als Maske dient. Meist kombiniert man die Methode mit blendFuncSeparate().

Parameter

Name	Typ	Default	Beschreibung
$modeRGB Pflicht	GLenum	gl.FUNC_ADD	Gleichung für die Rot-, Grün- und Blaukanäle: `gl.FUNC_ADD`, `gl.FUNC_SUBTRACT`, `gl.FUNC_REVERSE_SUBTRACT`, in WebGL 2 zusätzlich `gl.MIN` und `gl.MAX` (in WebGL 1 über `EXT_blend_minmax`: `ext.MIN_EXT`, `ext.MAX_EXT`).
$modeAlpha Pflicht	GLenum	gl.FUNC_ADD	Gleichung für den Alpha-Kanal; dieselben erlaubten Werte wie bei `modeRGB`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Getrennte Gleichungen setzen und auslesen

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

gl.enable(gl.BLEND);
// Farbe subtrahieren, Alpha normal addieren
gl.blendEquationSeparate(gl.FUNC_SUBTRACT, gl.FUNC_ADD);

const rgb = gl.getParameter(gl.BLEND_EQUATION_RGB);
const alpha = gl.getParameter(gl.BLEND_EQUATION_ALPHA);
console.log(rgb === gl.FUNC_SUBTRACT, alpha === gl.FUNC_ADD);

true true

Partikel: additive Farbe, maximaler Alpha-Wert (WebGL 2)

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

const drawParticles = () => {
  gl.enable(gl.BLEND);
  // Farben leuchten additiv auf, Alpha bleibt beim höchsten Wert
  gl.blendEquationSeparate(gl.FUNC_ADD, gl.MAX);
  gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ONE, gl.ONE);
  // ... gl.drawArrays(gl.POINTS, 0, particleCount);

  // Zustand für nachfolgende Draw-Calls zurücksetzen
  gl.blendEquation(gl.FUNC_ADD);
  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
};

drawParticles();

MIN/MAX in WebGL 1 über Erweiterung

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

gl.enable(gl.BLEND);
if (ext) {
  // Dunkelste Farbe gewinnt, Alpha wird addiert
  gl.blendEquationSeparate(ext.MIN_EXT, gl.FUNC_ADD);
} else {
  console.warn('EXT_blend_minmax nicht verfügbar – Fallback auf FUNC_ADD');
  gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);
}
console.log(gl.getError() === gl.NO_ERROR);

true

// Wichtig · Fallstricke

Übergibst du einen ungültigen Wert, erzeugt das den Fehler gl.INVALID_ENUM (abrufbar über gl.getError()). Eine Ausnahme wird dabei nicht geworfen.
gl.MIN und gl.MAX gibt es in WebGL 1 nicht. Dort brauchst du die Erweiterung EXT_blend_minmax und deren Konstanten MIN_EXT/MAX_EXT. Bei MIN/MAX werden die Blendfaktoren ignoriert.
Ohne gl.enable(gl.BLEND) hat die Einstellung keine sichtbare Wirkung.
Blend-Zustände sind global für den Kontext und bleiben bis zur nächsten Änderung bestehen. Setze sie nach Spezialeffekten zurück, sonst werden spätere Draw-Calls falsch gemischt.
Der Alpha-Kanal des Standard-Framebuffers beeinflusst, wie die Canvas mit der Seite zusammengesetzt wird (premultipliedAlpha, alpha in den Kontext-Attributen). Ungewöhnliche Alpha-Gleichungen können so zu unerwarteter Transparenz führen.
Wird von allen modernen Browsern unterstützt; unterschiedliche Gleichungen pro Draw-Buffer gibt es nur über OES_draw_buffers_indexed (blendEquationSeparateiOES).

Siehe auch

WebGLRenderingContext.blendEquation() WebGLRenderingContext.blendFuncSeparate() WebGLRenderingContext.blendFunc() WebGLRenderingContext.blendColor() WebGLRenderingContext.enable() WebGLRenderingContext.getParameter() WebGLRenderingContext