SVGFETurbulenceElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGFETurbulenceElement extends SVGElement

Beschreibung

SVGFETurbulenceElement steht im DOM für das SVG-Filterprimitiv <feTurbulence>. Dieses Primitiv erzeugt mit der Perlin-Turbulenzfunktion ein Rauschbild. Daraus lassen sich künstliche Texturen wie Wolken, Rauch, Marmor, Papierstruktur oder Filmkorn bauen. Oft wird das Ergebnis an <feDisplacementMap> weitergegeben, um andere Grafiken wellig oder „glitchig“ zu verzerren.

Das Interface erbt von SVGElement und bringt die Standard-Attribute für Filterprimitive mit: x, y, width, height und result. Dazu kommen diese eigenen, nur lesbaren Eigenschaften:

baseFrequencyX / baseFrequencyY (SVGAnimatedNumber): die Grundfrequenz des Rauschens in X- bzw. Y-Richtung, gelesen aus dem Attribut baseFrequency.
numOctaves (SVGAnimatedInteger): die Anzahl der Oktaven. Mehr Oktaven bedeuten mehr feine Details.
seed (SVGAnimatedNumber): der Startwert für den Zufallsgenerator.
stitchTiles (SVGAnimatedEnumeration): legt fest, ob die Kacheln nahtlos aneinandergesetzt werden (stitch) oder nicht (noStitch).
type (SVGAnimatedEnumeration): die Art des Rauschens, also fractalNoise oder turbulence.

Für die Aufzählungswerte gibt es Konstanten: SVG_TURBULENCE_TYPE_UNKNOWN (0), SVG_TURBULENCE_TYPE_FRACTALNOISE (1), SVG_TURBULENCE_TYPE_TURBULENCE (2) sowie SVG_STITCHTYPE_UNKNOWN (0), SVG_STITCHTYPE_STITCH (1) und SVG_STITCHTYPE_NOSTITCH (2). Das Interface ist nützlich, wenn man Filterparameter per Skript auslesen oder ändern will, etwa für animierte Wasser- oder Hitzeflimmer-Effekte oder für per Zufall erzeugte Hintergründe.

Rückgabewert

Typ

SVGFETurbulenceElement

Beschreibung

Instanzen bekommt man über document.createElementNS('http://www.w3.org/2000/svg', 'feTurbulence') oder über DOM-Abfragen wie querySelector('feTurbulence'). Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Rauschfilter per Skript erzeugen und anwenden

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

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

const turb = document.createElementNS(SVG_NS, 'feTurbulence');
turb.setAttribute('type', 'fractalNoise');
turb.setAttribute('baseFrequency', '0.02 0.05');
turb.setAttribute('numOctaves', '3');
turb.setAttribute('seed', '42');

filter.append(turb);
svg.querySelector('defs').append(filter);
svg.querySelector('rect').setAttribute('filter', 'url(#rauschen)');

console.log(turb instanceof SVGFETurbulenceElement);
console.log(turb.baseFrequencyX.baseVal, turb.baseFrequencyY.baseVal);

true 0.02 0.05

Eigenschaften und Aufzählungskonstanten auslesen

// <feTurbulence id="t" type="turbulence" stitchTiles="stitch" numOctaves="4"/>
const t = document.getElementById('t');

const typName = {
  [SVGFETurbulenceElement.SVG_TURBULENCE_TYPE_FRACTALNOISE]: 'fractalNoise',
  [SVGFETurbulenceElement.SVG_TURBULENCE_TYPE_TURBULENCE]: 'turbulence'
}[t.type.baseVal] ?? 'unbekannt';

console.log(typName);
console.log(t.numOctaves.baseVal);
console.log(t.stitchTiles.baseVal === SVGFETurbulenceElement.SVG_STITCHTYPE_STITCH);

turbulence 4 true

Animiertes Wasserflimmern mit feDisplacementMap

// <filter id="wasser">
//   <feTurbulence id="welle" type="turbulence" baseFrequency="0.01 0.04" numOctaves="2" result="noise"/>
//   <feDisplacementMap in="SourceGraphic" in2="noise" scale="12"/>
// </filter>
const welle = document.getElementById('welle');
const reduziert = matchMedia('(prefers-reduced-motion: reduce)').matches;

const animieren = (zeit) => {
  const fy = 0.04 + Math.sin(zeit / 1000) * 0.01;
  welle.setAttribute('baseFrequency', `0.01 ${fy.toFixed(4)}`);
  requestAnimationFrame(animieren);
};

if (!reduziert) requestAnimationFrame(animieren);

Zufällige Hintergrundtextur über den Seed

const turb = document.querySelector('#papier feTurbulence');
const neuerSeed = Math.floor(Math.random() * 1000);
turb.setAttribute('seed', String(neuerSeed));
console.log('Seed:', turb.seed.baseVal === neuerSeed);

Seed: true

// Wichtig · Fallstricke

Nur lesbare Eigenschaften: Die Eigenschaften selbst (baseFrequencyX, type usw.) lassen sich nicht neu zuweisen. Werte ändert man am zuverlässigsten mit setAttribute(). baseFrequencyX und baseFrequencyY kommen beide aus einem Attribut, baseFrequency. Steht dort nur ein Wert, gilt er für beide Richtungen.
Namensraum: Das Element muss mit createElementNS() und dem SVG-Namensraum angelegt werden. document.createElement('feTurbulence') erzeugt nur ein unbekanntes HTML-Element ohne Wirkung.
Leistung: Turbulenz wird pixelweise auf der CPU oder GPU berechnet. Hohe Werte für numOctaves (mehr als etwa 5 bis 6), große Filterbereiche und Änderungen in jedem Frame kosten spürbar Leistung, besonders auf Mobilgeräten. Bei Animationen prefers-reduced-motion beachten.
Browser-Unterschiede: Das Interface wird in allen modernen Browsern unterstützt. Das gerenderte Rauschen kann sich zwischen den Engines trotzdem leicht unterscheiden, zum Beispiel beim Farbraum (color-interpolation-filters). Nahtlose Kacheln mit stitchTiles="stitch" gelingen nur, wenn die Frequenz zur Kachelgröße passt.

Siehe auch

SVGFEBlendElement SVGFEFuncAElement SVGFEFuncBElement SVGFEFuncGElement SVGFEFuncRElement