WebGLRenderingContext.blendEquation() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.blendEquation(mode)

Beschreibung

blendEquation() bestimmt, wie die bereits mit den Blend-Faktoren gewichtete Quellfarbe (das neue Fragment) und Zielfarbe (der vorhandene Pixel im Framebuffer) miteinander verrechnet werden. Die Faktoren selbst legt man mit blendFunc() bzw. blendFuncSeparate() fest; blendEquation() wählt den Operator: Addition, Subtraktion oder umgekehrte Subtraktion (in WebGL 2 zusätzlich Minimum und Maximum).

Die Methode setzt die Gleichung für RGB und Alpha gleichzeitig. Sollen die Kanäle unterschiedlich behandelt werden, nutzt man stattdessen blendEquationSeparate(). Der Standardwert ist gl.FUNC_ADD, also Quelle * sFaktor + Ziel * dFaktor.

Die Einstellung wirkt nur, wenn Blending aktiviert ist: gl.enable(gl.BLEND). Typische Anwendungen sind Transparenz (FUNC_ADD), additive Lichteffekte und Partikel, „Abdunkeln“-Effekte per FUNC_REVERSE_SUBTRACT sowie in WebGL 2 Min-/Max-Akkumulation, z. B. für Maximum-Intensitäts-Projektionen.

FUNC_ADD: Quelle + Ziel
FUNC_SUBTRACT: Quelle − Ziel
FUNC_REVERSE_SUBTRACT: Ziel − Quelle
MIN / MAX (WebGL 2 oder Erweiterung EXT_blend_minmax): komponentenweises Minimum/Maximum, Blend-Faktoren werden dabei ignoriert

Parameter

Name	Typ	Default	Beschreibung
$mode Pflicht	GLenum (number)	gl.FUNC_ADD	Die Blend-Gleichung: `gl.FUNC_ADD`, `gl.FUNC_SUBTRACT`, `gl.FUNC_REVERSE_SUBTRACT`; mit WebGL 2 zusätzlich `gl.MIN` und `gl.MAX`, in WebGL 1 über `ext.MIN_EXT`/`ext.MAX_EXT` der Erweiterung `EXT_blend_minmax`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Klassische Alpha-Transparenz

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

gl.enable(gl.BLEND);
gl.blendEquation(gl.FUNC_ADD);
gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);

// Aktuelle Einstellung auslesen
console.log(gl.getParameter(gl.BLEND_EQUATION_RGB) === gl.FUNC_ADD);
console.log(gl.getParameter(gl.BLEND_EQUATION_ALPHA) === gl.FUNC_ADD);

true true

Abdunkeln per umgekehrter Subtraktion (Schatten-Decals)

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

gl.enable(gl.BLEND);
// Ergebnis = Ziel * 1 − Quelle * 1
gl.blendEquation(gl.FUNC_REVERSE_SUBTRACT);
gl.blendFunc(gl.ONE, gl.ONE);

// ... Schatten-Geometrie zeichnen ...

// Danach wieder auf Standard zurücksetzen
gl.blendEquation(gl.FUNC_ADD);

MAX-Blending mit WebGL 2 und Fallback auf die Erweiterung

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

const getMaxMode = () => {
  if (gl2) return gl2.MAX;
  const ext = gl.getExtension('EXT_blend_minmax');
  return ext ? ext.MAX_EXT : null;
};

const maxMode = getMaxMode();
if (maxMode !== null) {
  gl.enable(gl.BLEND);
  gl.blendEquation(maxMode); // hellster Wert gewinnt
  console.log('MAX-Blending aktiv');
} else {
  console.warn('MIN/MAX-Blending nicht verfügbar');
}

MAX-Blending aktiv

// Wichtig · Fallstricke

Blending muss aktiviert sein: Ohne gl.enable(gl.BLEND) hat blendEquation() keine sichtbare Wirkung.
Ungültiger Wert: Ein nicht unterstützter mode erzeugt gl.INVALID_ENUM (abfragbar mit gl.getError()). Es wird keine Exception geworfen, der Aufruf wird einfach ignoriert.
MIN/MAX in WebGL 1: gl.MIN/gl.MAX existieren im WebGL-1-Kontext nicht (undefined). Dort EXT_blend_minmax verwenden – die Erweiterung ist aber praktisch überall verfügbar.
Faktoren bei MIN/MAX: Die mit blendFunc() gesetzten Faktoren werden bei MIN/MAX ignoriert.
Globaler Zustand: Die Einstellung bleibt bis zur nächsten Änderung aktiv. Nach Spezialeffekten sollte man sie wieder auf FUNC_ADD zurücksetzen, sonst werden auch später gezeichnete Objekte falsch geblendet.
Premultiplied Alpha: Der Canvas wird standardmäßig mit vormultipliziertem Alpha zusammengesetzt; Subtraktions-Gleichungen können dadurch zu unerwarteten Alpha-Werten und sichtbaren Artefakten auf der Seite führen.
Kompatibilität: in allen modernen Browsern unterstützt, auch in Web Workern über OffscreenCanvas.

Siehe auch

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