Signatur
Beschreibung
Die Eigenschaft kernelUnitLengthX des Interfaces SVGFEDiffuseLightingElement gibt die horizontale Komponente des SVG-Attributs kernelUnitLength eines <feDiffuseLighting>-Filterprimitivs zurück. Das Attribut legt fest, wie groß eine „Zelle“ bei der Berechnung der Oberflächennormalen ist, gemessen in Einheiten des durch primitiveUnits bestimmten Koordinatensystems.
Der Rückgabewert ist ein SVGAnimatedNumber-Objekt. Über baseVal liest (und schreibt) man den im Markup festgelegten Grundwert, über animVal den aktuellen, ggf. durch SMIL-Animation veränderten Wert. Die Eigenschaft selbst ist schreibgeschützt – man kann ihr kein neues Objekt zuweisen, wohl aber baseVal ändern.
Enthält kernelUnitLength nur eine Zahl, gilt sie für X und Y gleichermaßen. Bei zwei Zahlen (z. B. kernelUnitLength="2 3") liefert kernelUnitLengthX die erste, kernelUnitLengthY die zweite. Ist das Attribut nicht gesetzt, ist baseVal in der Regel 0 – der Browser wählt dann selbst eine geeignete Auflösung.
Praktisch nutzt man die Eigenschaft, um Lichteffekte skalierungs- und geräteunabhängig zu gestalten oder um per Skript die Qualität bzw. Weichheit eines Beleuchtungsfilters dynamisch anzupassen.
Rückgabewert
baseVal (Grundwert, beschreibbar) und animVal (aktueller animierter Wert, schreibgeschützt) für die X-Komponente von kernelUnitLength.Beispiele
X-Komponente auslesen
// SVG-Markup:
// <svg width="200" height="200">
// <filter id="licht">
// <feDiffuseLighting id="diffus" kernelUnitLength="2 3" lighting-color="white">
// <fePointLight x="50" y="50" z="40" />
// </feDiffuseLighting>
// </filter>
// </svg>
const diffus = document.getElementById('diffus');
console.log(diffus.kernelUnitLengthX.baseVal);
console.log(diffus.kernelUnitLengthY.baseVal);Element per Skript erzeugen und Wert setzen
const SVG_NS = 'http://www.w3.org/2000/svg';
const filter = document.createElementNS(SVG_NS, 'filter');
const lighting = document.createElementNS(SVG_NS, 'feDiffuseLighting');
lighting.setAttribute('kernelUnitLength', '4');
filter.append(lighting);
// Eine Zahl gilt für X und Y
console.log(lighting.kernelUnitLengthX.baseVal, lighting.kernelUnitLengthY.baseVal);
// Grundwert direkt über baseVal ändern
lighting.kernelUnitLengthX.baseVal = 1.5;
console.log(lighting.getAttribute('kernelUnitLength'));Filterqualität per Schieberegler steuern
const diffus = document.querySelector('feDiffuseLighting');
const regler = document.querySelector('#aufloesung'); // <input type="range" min="0.5" max="5" step="0.5">
regler.addEventListener('input', () => {
const wert = Number(regler.value);
diffus.kernelUnitLengthX.baseVal = wert;
diffus.kernelUnitLengthY.baseVal = wert;
console.log(`kernelUnitLength: ${diffus.kernelUnitLengthX.animVal}`);
});// Wichtig · Fallstricke
- Die Eigenschaft ist schreibgeschützt:
el.kernelUnitLengthX = 2bleibt wirkungslos (bzw. wirft im Strict Mode einenTypeError). Ändern Sie stattdessenel.kernelUnitLengthX.baseValoder das Attribut persetAttribute(). - Ist
kernelUnitLengthnicht gesetzt, liefertbaseValmeist0; das bedeutet „vom Browser bestimmt“, nicht „keine Auflösung“. - Negative Werte oder
0im Attribut sind laut Spezifikation ein Fehler; der Filter kann dann deaktiviert werden. - Sehr kleine Werte führen zu feiner, aber rechenintensiver Beleuchtung und können auf großen Flächen die Darstellung spürbar verlangsamen.
- Die Unterstützung des Attributs in der Render-Pipeline schwankt zwischen den Browsern (insbesondere Chromium ignoriert
kernelUnitLengthteils beim Rendern), obwohl die DOM-Eigenschaft überall vorhanden ist. Ergebnis daher visuell prüfen.