CanvasRenderingContext2D.globalCompositeOperation — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.globalCompositeOperation

Beschreibung

Mit globalCompositeOperation legst du fest, wie alles, was du danach zeichnest (Formen, Text, Bilder), mit den Pixeln verrechnet wird, die schon auf dem Canvas sind. Standardwert ist "source-over": Neues wird einfach über den bestehenden Inhalt gelegt.

Es gibt zwei Gruppen von Werten:

Porter-Duff-Operatoren wie source-in, source-out, source-atop, destination-over, destination-in, destination-out, destination-atop, lighter, copy und xor. Sie steuern über die Alpha-Kanäle, welche Bereiche sichtbar bleiben. Damit lassen sich Masken, Ausstanzungen und Radiergummis bauen.
Mischmodi (Blend Modes) wie multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, hue, saturation, color und luminosity. Sie verrechnen die Farbwerte so, wie man es von Bildbearbeitungsprogrammen und CSS mix-blend-mode kennt.

Die Eigenschaft gehört zum Zeichenzustand. Sie wird also mit save() gesichert und mit restore() zurückgesetzt. Sie wirkt nur auf Zeichenaufrufe nach dem Setzen, bereits Gezeichnetes bleibt unverändert.

Parameter

Name	Typ	Default	Beschreibung
$value	string	"source-over"	Name der Kompositionsoperation, z. B. `"source-over"`, `"destination-out"`, `"multiply"` oder `"xor"`. Unbekannte Werte werden stillschweigend ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuell eingestellte Name der Kompositionsoperation, standardmäßig "source-over".

Beispiele

Radiergummi mit destination-out

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

// Hintergrund füllen
ctx.fillStyle = '#3498db';
ctx.fillRect(0, 0, canvas.width, canvas.height);

// Beim Ziehen mit der Maus Pixel transparent machen
canvas.addEventListener('pointermove', (e) => {
  if (e.buttons !== 1) return;
  ctx.save();
  ctx.globalCompositeOperation = 'destination-out';
  ctx.beginPath();
  ctx.arc(e.offsetX, e.offsetY, 15, 0, Math.PI * 2);
  ctx.fill(); // die Farbe ist egal, entscheidend ist nur Alpha
  ctx.restore();
});

Bild in eine Kreisform maskieren (source-in)

const ctx = document.querySelector('canvas').getContext('2d');
const img = new Image();
img.src = 'avatar.jpg';
await img.decode();

// 1. Maske zeichnen
ctx.beginPath();
ctx.arc(100, 100, 100, 0, Math.PI * 2);
ctx.fill();

// 2. Bild nur dort zeichnen, wo die Maske liegt
ctx.globalCompositeOperation = 'source-in';
ctx.drawImage(img, 0, 0, 200, 200);

// 3. Zurück auf den Standardwert
ctx.globalCompositeOperation = 'source-over';
console.log(ctx.globalCompositeOperation);

source-over

Farbmischung mit multiply

const ctx = document.querySelector('canvas').getContext('2d');

ctx.globalCompositeOperation = 'multiply';
ctx.fillStyle = 'cyan';
ctx.beginPath(); ctx.arc(80, 80, 60, 0, Math.PI * 2); ctx.fill();
ctx.fillStyle = 'magenta';
ctx.beginPath(); ctx.arc(140, 80, 60, 0, Math.PI * 2); ctx.fill();
ctx.fillStyle = 'yellow';
ctx.beginPath(); ctx.arc(110, 130, 60, 0, Math.PI * 2); ctx.fill();
// Überlappungen ergeben Blau, Rot, Grün und in der Mitte Schwarz

Ungültige Werte werden ignoriert

const ctx = document.createElement('canvas').getContext('2d');
ctx.globalCompositeOperation = 'screen';
ctx.globalCompositeOperation = 'gibt-es-nicht';
console.log(ctx.globalCompositeOperation);

screen

// Wichtig · Fallstricke

Keine Fehlermeldung: Tippfehler wie "source_over" werfen keinen Fehler. Die Zuweisung wird einfach ignoriert und der alte Wert bleibt aktiv. Lies den Wert im Zweifel zur Kontrolle zurück.
Setz den Wert zurück: Wenn du nach einer Operation vergisst, auf "source-over" zurückzustellen, zeichnen alle folgenden Aufrufe ebenfalls mit dieser Operation. Rahme den Wechsel am besten mit save()/restore() ein.
Operationen, die das ganze Canvas betreffen: source-in, source-out, destination-in, destination-atop und copy verändern auch Pixel außerhalb der gezeichneten Form, dort wird das Ziel meist gelöscht. Das überrascht oft.
Nicht mit anderen Werkzeugen verwechseln: clearRect() und putImageData() werden von der Kompositionsoperation nicht beeinflusst. globalAlpha, Schatten und filter dagegen schon.
Leistung: Mischmodi wie hue oder luminosity sind aufwendiger als Porter-Duff-Operatoren. Bei Animationen auf großen Canvas-Flächen sinkt dadurch unter Umständen die Bildrate.
Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft einschließlich der Mischmodi, ebenso OffscreenCanvasRenderingContext2D. Der alte Wert "darker" ist nicht standardisiert und wird nicht unterstützt.

Siehe auch

CanvasRenderingContext2D CanvasRenderingContext2D.globalAlpha CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D.drawImage() CanvasRenderingContext2D.clip()