PannerNode.maxDistance — Eigenschaft · JavaScript-Referenz

Signatur

PannerNode.maxDistance

Beschreibung

Die Eigenschaft maxDistance eines PannerNode ist eine Gleitkommazahl (double). Sie gibt an, ab welcher Entfernung zwischen Schallquelle und AudioListener die Lautstärke nicht mehr weiter sinkt. Der Wert lässt sich lesen und schreiben. Standardmäßig ist er 10000, die Einheit ist dieselbe wie bei den Positionskoordinaten (frei wählbar, z. B. Meter).

Am wichtigsten ist maxDistance beim Entfernungsmodell distanceModel = "linear". Dort bestimmt der Wert, wo die lineare Dämpfung endet: Die Entfernung wird auf den Bereich zwischen refDistance und maxDistance begrenzt. Die Verstärkung berechnet sich dann so: 1 - rolloffFactor * (d - refDistance) / (maxDistance - refDistance). Bei rolloffFactor = 1 ist die Quelle ab maxDistance also völlig stumm.

Bei den Modellen "inverse" (Standard) und "exponential" hat maxDistance laut Spezifikation keinen Einfluss. Diese Modelle begrenzen die Entfernung nur nach unten, nämlich auf refDistance. Typische Einsatzfälle sind Spiele, 3D-Szenen und virtuelle Räume, in denen Geräusche ab einer bestimmten Entfernung nicht mehr (oder nur noch sehr leise) zu hören sein sollen.

Parameter

Name	Typ	Default	Beschreibung
$wert	number	10000	Beim Schreiben: neue maximale Entfernung. Muss eine positive Zahl sein (größer als `0`).

Rückgabewert

Typ

number

Beschreibung

Die aktuell gesetzte maximale Entfernung als double.

Beispiele

Wert lesen und setzen

const ctx = new AudioContext();
const panner = new PannerNode(ctx);

console.log(panner.maxDistance); // Standardwert

panner.maxDistance = 50;
console.log(panner.maxDistance);

10000 50

Lineares Ausblenden bis 30 Meter in einer Spielszene

const ctx = new AudioContext();

const panner = new PannerNode(ctx, {
  panningModel: 'HRTF',
  distanceModel: 'linear', // nur hier wirkt maxDistance
  refDistance: 1,
  maxDistance: 30,
  rolloffFactor: 1,
  positionX: 0,
  positionY: 0,
  positionZ: -5
});

const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(panner).connect(ctx.destination);
osc.start();

// Quelle entfernt sich: ab 30 Einheiten ist sie stumm
let z = -5;
const timer = setInterval(() => {
  z -= 1;
  panner.positionZ.value = z;
  if (z < -40) {
    clearInterval(timer);
    osc.stop();
  }
}, 100);

Verstärkung für das lineare Modell nachrechnen

const linearGain = ({ refDistance, maxDistance, rolloffFactor }, distance) => {
  const d = Math.min(Math.max(distance, refDistance), maxDistance);
  return 1 - rolloffFactor * (d - refDistance) / (maxDistance - refDistance);
};

const opts = { refDistance: 1, maxDistance: 21, rolloffFactor: 1 };
for (const dist of [1, 11, 21, 100]) {
  console.log(dist, linearGain(opts, dist).toFixed(2));
}

1 1.00 11 0.50 21 0.00 100 0.00

Ungültige Werte abfangen

const ctx = new AudioContext();
const panner = ctx.createPanner();

try {
  panner.maxDistance = 0;
} catch (err) {
  console.log(err.name);
}
console.log(panner.maxDistance);

RangeError 10000

// Wichtig · Fallstricke

RangeError: Wird ein Wert kleiner oder gleich 0 gesetzt, wirft der Browser einen RangeError. Der bisherige Wert bleibt dann erhalten.
Wirkt fast nur beim linearen Modell: Bei "inverse" (Standard) und "exponential" ändert maxDistance laut Spezifikation nichts. Soll eine Quelle ab einer bestimmten Entfernung verstummen, muss distanceModel = "linear" gesetzt sein.
Nicht automatisierbar: maxDistance ist ein einfacher Zahlenwert und kein AudioParam. Methoden wie linearRampToValueAtTime() stehen deshalb nicht zur Verfügung.
Lautstärke unter dem Nullwert: Ist rolloffFactor kleiner als 1, bleibt die Quelle auch jenseits von maxDistance hörbar, mit der Restlautstärke 1 - rolloffFactor.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Die Einstellung über den Konstruktor (new PannerNode(ctx, { maxDistance })) gibt es erst in neueren Versionen. In sehr alten Safari-Versionen ist nur webkitAudioContext mit createPanner() verfügbar.

Siehe auch

PannerNode PannerNode.refDistance PannerNode.rolloffFactor PannerNode.distanceModel AudioListener BaseAudioContext.createPanner() PannerNode.coneOuterAngle