SVGFEConvolveMatrixElement.bias — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEConvolveMatrixElement.bias

Beschreibung

Die schreibgeschützte Eigenschaft bias der Schnittstelle SVGFEConvolveMatrixElement gibt ein SVGAnimatedNumber-Objekt zurück. Dieses Objekt spiegelt das SVG-Attribut bias des zugehörigen <feConvolveMatrix>-Filterprimitivs wider.

Bei der Faltung wird bias nach der Division durch divisor auf das Ergebnis jedes Farbkanals addiert. Damit verschieben Sie den Wertebereich des Ergebnisses. Das ist z. B. bei Relief- oder Kantenfiltern (Emboss) nützlich: Negative Ergebnisse würden sonst auf Schwarz bzw. Transparent abgeschnitten. Mit einem bias von 0.5 landet eine „neutrale“ Fläche im mittleren Grau. Fehlt das Attribut, ist der Wert 0.

Schreibgeschützt ist nur die Eigenschaft selbst, also der Verweis auf das SVGAnimatedNumber-Objekt. Den eigentlichen Wert können Sie über bias.baseVal lesen und schreiben. bias.animVal enthält den aktuell wirksamen, eventuell durch SMIL animierten Wert und lässt sich nur lesen.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Ein Objekt mit baseVal (lesbar und schreibbar, Basiswert des Attributs) und animVal (nur lesbar, aktuell animierter Wert). Ohne gesetztes Attribut sind beide Werte 0.

Beispiele

bias-Wert auslesen

// HTML: <svg><filter id="relief"><feConvolveMatrix id="conv" kernelMatrix="-2 -1 0 -1 1 1 0 1 2" bias="0.5"/></filter></svg>
const conv = document.getElementById('conv');

console.log(conv.bias instanceof SVGAnimatedNumber);
console.log(conv.bias.baseVal);
console.log(conv.bias.animVal);

true 0.5 0.5

Filter per JavaScript erzeugen und bias setzen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
const filter = document.createElementNS(SVG_NS, 'filter');
filter.id = 'emboss';

const conv = document.createElementNS(SVG_NS, 'feConvolveMatrix');
conv.setAttribute('order', '3');
conv.setAttribute('kernelMatrix', '-2 -1 0 -1 1 1 0 1 2');

console.log(conv.bias.baseVal); // Standardwert
conv.bias.baseVal = 0.5;        // setzt das Attribut bias="0.5"
console.log(conv.getAttribute('bias'));

filter.append(conv);
svg.append(filter);
document.body.append(svg);
document.querySelector('img').style.filter = 'url(#emboss)';

0 0.5

bias mit einem Schieberegler interaktiv anpassen

// HTML: <input type="range" id="biasSlider" min="-1" max="1" step="0.05" value="0">
const slider = document.getElementById('biasSlider');
const conv = document.querySelector('#relief feConvolveMatrix');

slider.addEventListener('input', () => {
  conv.bias.baseVal = Number(slider.value);
  console.log(`bias = ${conv.bias.baseVal}`);
});

bias = 0.25 (je nach Reglerstellung)

// Wichtig · Fallstricke

Keine direkte Zuweisung: conv.bias = 0.5 hat keine Wirkung (im Strict Mode wird ein TypeError geworfen), denn die Eigenschaft ist schreibgeschützt. Schreiben Sie stattdessen in conv.bias.baseVal oder nutzen Sie setAttribute('bias', ...).
Wertebereich: bias gilt für normierte Farbwerte zwischen 0 und 1. Ein Wert von 0.5 verschiebt das Ergebnis um die Hälfte des Farbbereichs, nicht um 0,5 von 255.
Alphakanal: Bei preserveAlpha="false" (Standard) wird bias auch auf den Alphakanal angewendet. Das kann unerwartet halbtransparente oder deckende Flächen erzeugen. Browser behandeln das zudem teilweise unterschiedlich, weil die Spezifikation bias auf vormultiplizierte Farbwerte anwendet.
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern (Chrome, Firefox, Safari, Edge) unterstützt. SMIL-Animationen des Attributs sind nur über animVal sichtbar.

Siehe auch

SVGFEConvolveMatrixElement SVGFEConvolveMatrixElement.divisor SVGFEConvolveMatrixElement.kernelMatrix SVGFEConvolveMatrixElement.preserveAlpha SVGAnimatedNumber SVGFEConvolveMatrixElement.result