SVGFESpecularLightingElement.kernelUnitLengthY — Eigenschaft · JavaScript-Referenz

Signatur

SVGFESpecularLightingElement.kernelUnitLengthY

Beschreibung

Die Eigenschaft kernelUnitLengthY der Schnittstelle SVGFESpecularLightingElement gibt den zweiten Wert (y-Richtung) des Attributs kernelUnitLength zurück. Das Attribut legt fest, welcher Abstand in Einheiten des aktuellen Filterkoordinatensystems (primitiveUnits) zwischen zwei Zellen des Rasters liegt, auf dem die Oberflächennormalen für die Glanzlicht-Berechnung ermittelt werden.

Enthält kernelUnitLength nur einen Wert, gilt er für beide Richtungen. kernelUnitLengthY hat dann denselben Wert wie kernelUnitLengthX. Fehlt das Attribut ganz, rechnet der Browser mit seiner eigenen Pixelauflösung. Der Basiswert steht dann auf 0.

Der Rückgabewert ist ein SVGAnimatedNumber. Der festgelegte Wert steht in baseVal, der Wert inklusive laufender SMIL-Animationen in animVal. Die Eigenschaft selbst kannst du nicht neu zuweisen. baseVal lässt sich in vielen Browsern setzen. Portabler ist es aber, setAttribute('kernelUnitLength', …) zu verwenden, weil das die Werte für x und y gemeinsam ändert.

Du brauchst die Eigenschaft vor allem, um Beleuchtungsfilter unabhängig von der Bildschirmauflösung zu machen. Sonst kann sich der Glanzeffekt auf HiDPI-Bildschirmen oder beim Zoomen sichtbar verändern.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit baseVal (festgelegter y-Wert von kernelUnitLength, als number) und animVal (aktueller, eventuell animierter Wert). Die Eigenschaft selbst ist schreibgeschützt.

Beispiele

y-Wert von kernelUnitLength auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const filter = document.createElementNS(svgNS, 'filter');
const light = document.createElementNS(svgNS, 'feSpecularLighting');
light.setAttribute('kernelUnitLength', '2 3');
filter.appendChild(light);

console.log(light.kernelUnitLengthX.baseVal);
console.log(light.kernelUnitLengthY.baseVal);

2 3

Nur ein Wert angegeben: y übernimmt den Wert von x

const light = document.createElementNS('http://www.w3.org/2000/svg', 'feSpecularLighting');
light.setAttribute('kernelUnitLength', '1.5');

const { kernelUnitLengthX, kernelUnitLengthY } = light;
console.log(kernelUnitLengthX.baseVal, kernelUnitLengthY.baseVal);

1.5 1.5

Auflösung eines Glanzfilters abhängig von der Pixeldichte anpassen

// HTML: <svg><filter id="glanz"><feSpecularLighting id="spec" surfaceScale="5" specularExponent="20"><fePointLight x="50" y="50" z="100"/></feSpecularLighting></filter></svg>
const spec = document.querySelector('#spec');

const updateKernel = () => {
  const unit = 1 / window.devicePixelRatio;
  // x und y gemeinsam über das Attribut setzen
  spec.setAttribute('kernelUnitLength', `${unit} ${unit}`);
  console.log('Y-Kernel:', spec.kernelUnitLengthY.baseVal);
};

updateKernel();
matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`)
  .addEventListener('change', updateKernel);

Y-Kernel: 0.5 (bei devicePixelRatio = 2)

// Wichtig · Fallstricke

Schreibgeschützt: Wenn du light.kernelUnitLengthY = 2 zuweist, passiert nichts (im Strict-Modus gibt es einen TypeError). Ändere stattdessen das Attribut oder baseVal.
Standardwert: Ohne kernelUnitLength-Attribut liefert baseVal den Wert 0. Das bedeutet „vom Browser gewählt“ und ist kein echter Abstand von null.
Ungültige Werte: Negative Werte oder 0 im Attribut sind laut Spezifikation ein Fehler. Der Filter verhält sich dann so, als wäre das Attribut nicht gesetzt.
Browser-Unterstützung: Die Eigenschaft ist über das DOM in allen modernen Browsern verfügbar. Beim tatsächlichen Rendern wird kernelUnitLength aber teilweise ignoriert (zum Beispiel in Chromium). Ergebnisse können sich deshalb von Browser zu Browser optisch unterscheiden.
Leistung: Kleine Werte bedeuten ein feineres Raster, also mehr Rechenaufwand beim Filtern. Das fällt besonders bei großen Flächen oder bei Animationen ins Gewicht.

Siehe auch

SVGFESpecularLightingElement.kernelUnitLengthX SVGFESpecularLightingElement SVGFEDiffuseLightingElement.kernelUnitLengthY SVGAnimatedNumber SVGFESpecularLightingElement.specularExponent Element.setAttribute()