SVGFEDistantLightElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGFEDistantLightElement extends SVGElement

Beschreibung

Die Schnittstelle SVGFEDistantLightElement ist die DOM-Darstellung des Elements <feDistantLight>. Es beschreibt eine gerichtete Lichtquelle, deren Strahlen parallel verlaufen, als wäre sie unendlich weit entfernt. Das Element wird als Kind von <feDiffuseLighting> oder <feSpecularLighting> innerhalb eines <filter> verwendet, um Reliefeffekte, Prägungen oder gleichmäßige Schattierungen zu erzeugen.

Die Richtung des Lichts wird über zwei Winkel festgelegt:

azimuth – Richtungswinkel in der XY-Ebene (in Grad, im Uhrzeigersinn von der x-Achse aus).
elevation – Höhenwinkel über der XY-Ebene (in Grad, 0 = flach, 90 = senkrecht von oben).

Beide Werte stehen im DOM als schreibgeschützte Eigenschaften vom Typ SVGAnimatedNumber zur Verfügung. Den aktuellen Wert liest man über .baseVal bzw. den animierten Wert über .animVal. Zum Ändern setzt man baseVal direkt oder nutzt setAttribute() – so lassen sich Lichteffekte per JavaScript dynamisch animieren, etwa abhängig von der Mausposition.

Die Schnittstelle besitzt keinen eigenen Konstruktor. Instanzen erzeugt man mit document.createElementNS("http://www.w3.org/2000/svg", "feDistantLight") oder erhält sie aus bestehendem SVG-Markup, etwa per querySelector().

Parameter

Name	Typ	Default	Beschreibung
$azimuth	SVGAnimatedNumber	0	Schreibgeschützte Eigenschaft; spiegelt das Attribut `azimuth` wider (Richtungswinkel in Grad in der XY-Ebene).
$elevation	SVGAnimatedNumber	0	Schreibgeschützte Eigenschaft; spiegelt das Attribut `elevation` wider (Höhenwinkel in Grad über der Zeichenebene).

Rückgabewert

Typ

SVGFEDistantLightElement

Beschreibung

Ein Element-Objekt, das über createElementNS() oder DOM-Abfragen gewonnen wird; kein direkter Konstruktor.

Beispiele

Vorhandenes feDistantLight auslesen

// HTML:
// <svg width="200" height="200">
//   <filter id="licht">
//     <feDiffuseLighting in="SourceGraphic" lighting-color="white">
//       <feDistantLight id="sonne" azimuth="45" elevation="30" />
//     </feDiffuseLighting>
//   </filter>
//   <circle cx="100" cy="100" r="80" fill="steelblue" filter="url(#licht)" />
// </svg>

const light = document.querySelector('#sonne');
console.log(light instanceof SVGFEDistantLightElement);
console.log(light.azimuth.baseVal, light.elevation.baseVal);

true 45 30

Filter mit gerichtetem Licht per JavaScript erzeugen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');

const filter = document.createElementNS(SVG_NS, 'filter');
filter.id = 'relief';

const lighting = document.createElementNS(SVG_NS, 'feSpecularLighting');
lighting.setAttribute('in', 'SourceAlpha');
lighting.setAttribute('specularExponent', '20');
lighting.setAttribute('lighting-color', '#ffd');

const light = document.createElementNS(SVG_NS, 'feDistantLight');
light.azimuth.baseVal = 225;
light.elevation.baseVal = 45;

lighting.append(light);
filter.append(lighting);
svg.prepend(filter);

console.log(light.getAttribute('azimuth'));

225

Lichtrichtung mit der Maus steuern

const light = document.querySelector('#sonne');
const svg = light.ownerSVGElement;

svg.addEventListener('pointermove', (event) => {
  const rect = svg.getBoundingClientRect();
  const dx = event.clientX - (rect.left + rect.width / 2);
  const dy = event.clientY - (rect.top + rect.height / 2);
  // Winkel in Grad berechnen und auf 0–360 normalisieren
  const angle = (Math.atan2(dy, dx) * 180 / Math.PI + 360) % 360;
  light.azimuth.baseVal = angle;
});

// Wichtig · Fallstricke

Namensraum beachten: document.createElement('feDistantLight') erzeugt nur ein unbekanntes HTML-Element ohne Wirkung. Immer createElementNS() mit dem SVG-Namensraum verwenden.
azimuth und elevation sind SVGAnimatedNumber-Objekte, keine Zahlen. light.azimuth = 45 hat keine Wirkung – richtig ist light.azimuth.baseVal = 45.
Das Element wirkt nur als direktes Kind von feDiffuseLighting oder feSpecularLighting. Pro Beleuchtungsfilter sollte genau eine Lichtquelle vorhanden sein; weitere werden ignoriert.
Performance: Beleuchtungsfilter werden pixelweise berechnet. Häufige Änderungen (z. B. bei pointermove) auf großen Flächen können teuer werden – gegebenenfalls mit requestAnimationFrame drosseln.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Leichte Unterschiede in der Darstellung zwischen Rendering-Engines sind möglich.

Siehe auch

SVGFEPointLightElement SVGFESpotLightElement SVGFEDiffuseLightingElement SVGFEImageElement SVGAnimationElement