Signatur
Beschreibung
SVGFEConvolveMatrixElement ist die DOM-Schnittstelle des Elements <feConvolveMatrix>. Das Filterprimitiv berechnet jedes Ausgabepixel aus dem Pixel selbst und seinen Nachbarn im Eingabebild. Diese Werte werden mit einer Matrix gewichtet, dem sogenannten Kernel. Die gewichtete Summe wird durch divisor geteilt, danach wird bias addiert. Damit setzt du klassische Bildverarbeitungseffekte um: Schärfen, Prägen (Emboss), Kantenerkennung oder einfache Box-Weichzeichner. Das funktioniert direkt in SVG und über filter: url(#id) auch für HTML-Elemente wie <img>, <video> oder <canvas>.
Die Schnittstelle erbt von SVGElement. Außerdem bringt sie die Eigenschaften von SVGFilterPrimitiveStandardAttributes mit: x, y, width, height und result. Alle spezifischen Eigenschaften sind animierbare Objekte (SVGAnimatedInteger, SVGAnimatedNumber, SVGAnimatedNumberList, SVGAnimatedEnumeration, SVGAnimatedBoolean, SVGAnimatedString). Den im Markup gesetzten Wert liest du über baseVal. Den Wert, den eine SMIL-Animation gerade erzeugt, liest du über animVal; dieser ist nur lesbar.
Für die Kantenbehandlung (edgeMode) gibt es statische Konstanten: SVG_EDGEMODE_UNKNOWN (0), SVG_EDGEMODE_DUPLICATE (1), SVG_EDGEMODE_WRAP (2) und SVG_EDGEMODE_NONE (3). Sie legen fest, wie Pixel außerhalb des Eingabebildes behandelt werden: Randpixel wiederholen, das Bild auf der Gegenseite fortsetzen oder transparent schwarz annehmen.
In der Praxis änderst du die Filterparameter meist per setAttribute(), z. B. um den Kernel abhängig von einer Nutzereinstellung umzuschalten. Die animierten Eigenschaften eignen sich gut zum Auslesen. Bei kernelMatrix.baseVal (einer SVGNumberList) kannst du einzelne Einträge auch direkt ändern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $in1 | SVGAnimatedString | Ergebnis des vorherigen Primitivs bzw. SourceGraphic | Entspricht dem Attribut in: die Eingabe des Filters, z. B. SourceGraphic, SourceAlpha oder der result-Name eines anderen Primitivs. |
| $orderX | SVGAnimatedInteger | 3 | Anzahl der Spalten des Kernels (erster Wert des Attributs order). Muss größer als 0 sein. |
| $orderY | SVGAnimatedInteger | Wert von orderX | Anzahl der Zeilen des Kernels (zweiter Wert von order). |
| $kernelMatrix Pflicht | SVGAnimatedNumberList | Die Gewichte des Kernels, zeilenweise angegeben. Die Anzahl muss genau orderX * orderY betragen. |
|
| $divisor | SVGAnimatedNumber | Summe aller Kernel-Werte (1, wenn die Summe 0 ist) | Durch diesen Wert wird die gewichtete Summe geteilt. Der Wert 0 ist ein Fehler und wird durch den Standardwert ersetzt. |
| $bias | SVGAnimatedNumber | 0 | Wird nach der Division zum Ergebnis addiert. Das ist nützlich bei Prägeeffekten, damit neutrale Flächen grau statt schwarz erscheinen (z. B. 0.5). |
| $targetX | SVGAnimatedInteger | floor(orderX / 2) | Spalte im Kernel, die auf das Zielpixel ausgerichtet wird (0 ≤ targetX < orderX). |
| $targetY | SVGAnimatedInteger | floor(orderY / 2) | Zeile im Kernel, die auf das Zielpixel ausgerichtet wird (0 ≤ targetY < orderY). |
| $edgeMode | SVGAnimatedEnumeration | 1 (SVG_EDGEMODE_DUPLICATE) | Kantenbehandlung als Zahl: 1 = duplicate, 2 = wrap, 3 = none, 0 = unbekannt. |
| $kernelUnitLengthX | SVGAnimatedNumber | Horizontaler Abstand zwischen Kernel-Spalten in Benutzereinheiten (Attribut kernelUnitLength). Browser unterstützen das nur eingeschränkt. |
|
| $kernelUnitLengthY | SVGAnimatedNumber | Vertikaler Abstand zwischen Kernel-Zeilen in Benutzereinheiten. | |
| $preserveAlpha | SVGAnimatedBoolean | false | Bei true wird nur auf die Farbkanäle gefaltet und der Alphakanal des Eingabebildes bleibt erhalten. Bei false wird auch Alpha gefaltet. |
Rückgabewert
<feConvolveMatrix> oder durch document.createElementNS('http://www.w3.org/2000/svg', 'feConvolveMatrix'). Einen öffentlichen Konstruktor gibt es nicht.