SVGFEDiffuseLightingElement.surfaceScale — Eigenschaft · JavaScript-Referenz

Signatur

SVGFEDiffuseLightingElement.surfaceScale

Beschreibung

Die schreibgeschützte Eigenschaft surfaceScale der Schnittstelle SVGFEDiffuseLightingElement gibt ein SVGAnimatedNumber-Objekt zurück. Es steht für das Attribut surfaceScale des Elements <feDiffuseLighting>. Dieser Faktor legt fest, wie stark die Alpha-Werte des Eingabebildes als Höhenkarte gewertet werden. Er bestimmt also, wie „erhaben“ die beleuchtete Oberfläche erscheint.

Schreibgeschützt ist nur die Eigenschaft selbst, also der Verweis auf das SVGAnimatedNumber-Objekt. Über surfaceScale.baseVal kannst du den Grundwert lesen und schreiben. surfaceScale.animVal liefert den aktuellen Wert, auf den gerade laufende SMIL-Animationen bereits angewendet sind. Dieser Wert ist nur lesbar.

Fehlt das Attribut, beträgt der Standardwert 1. Größere Werte ergeben stärkere Reliefeffekte. Negative Werte kehren die Höhenkarte um, sodass die Oberfläche eingedrückt statt erhaben wirkt. Typische Anwendungsfälle sind interaktive Relief- und Prägeeffekte, Texturen oder Beleuchtung, die per Skript animiert wird.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Ein Objekt mit baseVal (Grundwert, lesbar und schreibbar) und animVal (aktueller Wert nach Animationen, nur lesbar). Standardwert ist 1.

Beispiele

Aktuellen Wert auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const lighting = document.createElementNS(svgNS, 'feDiffuseLighting');
lighting.setAttribute('surfaceScale', '5');

console.log(lighting.surfaceScale.baseVal);
console.log(lighting.surfaceScale.animVal);

5 5

Standardwert ohne Attribut

const lighting = document.createElementNS('http://www.w3.org/2000/svg', 'feDiffuseLighting');
console.log(lighting.surfaceScale.baseVal);
console.log(lighting.hasAttribute('surfaceScale'));

1 false

Relief-Stärke per Schieberegler steuern

// HTML: <input type="range" id="relief" min="-10" max="10" step="0.5" value="1">
// SVG:  <filter id="emboss"><feDiffuseLighting id="light" in="SourceAlpha">
//         <feDistantLight azimuth="45" elevation="45"/></feDiffuseLighting></filter>
const light = document.getElementById('light');
const slider = document.getElementById('relief');

slider.addEventListener('input', () => {
  // baseVal ist schreibbar und aktualisiert zugleich das Attribut
  light.surfaceScale.baseVal = Number(slider.value);
  console.log('surfaceScale =', light.getAttribute('surfaceScale'));
});

surfaceScale = 3.5 (je nach Reglerstellung)

// Wichtig · Fallstricke

Eine direkte Zuweisung wie el.surfaceScale = 3 hat keine Wirkung, weil die Eigenschaft schreibgeschützt ist. Im Strict Mode wird dabei ein TypeError ausgelöst. Setze stattdessen el.surfaceScale.baseVal = 3 oder rufe setAttribute('surfaceScale', '3') auf.
Achte auf die Groß- und Kleinschreibung: Das Attribut heißt surfaceScale mit großem „S“. Wenn du Elemente erzeugst, verwende createElementNS mit dem SVG-Namensraum und nicht createElement. Sonst entsteht kein SVGFEDiffuseLightingElement, und surfaceScale ist undefined.
animVal weicht von baseVal nur ab, solange eine SMIL-Animation (<animate>) auf das Attribut wirkt.
Beleuchtungsfilter sind rechenintensiv. Wenn du den Wert häufig änderst, etwa bei jedem input-Ereignis auf großen Flächen, kann das die Darstellung verlangsamen. Drossle solche Aktualisierungen gegebenenfalls, zum Beispiel mit requestAnimationFrame.
Die Eigenschaft wird von allen modernen Browsern unterstützt.

Siehe auch

SVGFEDiffuseLightingElement SVGFEDiffuseLightingElement.diffuseConstant SVGFEDiffuseLightingElement.kernelUnitLengthX SVGFESpecularLightingElement.surfaceScale SVGAnimatedNumber