alListener

alListener

Name

alListener - Setzt Eigenschaften eines Listener-Objektes der AL.

Delphi-Spezifikation

procedure alListenerf(param: TALenum; value: TALfloat);
procedure alListener3f(param: TALenum; v1: TALfloat; v2: TALfloat; v3: TALfloat);
procedure alListenerfv(param: TALenum; values: PALfloat);
procedure alListeneri(param: TALenum; value: TALint);
procedure alListener3i(param: TALenum; v1: TALint; v2: TALint; v3: TALint);
procedure alListeneriv(param: TALenum; values: PALint);

Parameter

param	Symbolische Konstante, welche die zu setzende Eigenschaft angibt
value	TALfloat-/ TALint-Wert, der gesetzt werden soll (nur bei alListenerf und alListeneri)
values	Zeiger auf einen TALfloat-/ TALint-Vektor, welcher die zu setzenden Werte enthält (nur bei alListenerfv und alListeneriv)
v1, v2, v3	TALfloat-/ TALint-Werte, welche die zu setzenden Werte angeben (nur bei alListener3f und alListener3i)

Beschreibung

Die Funktion alListener bzw. ihre Varianten für verschiedene Wertargumente setzen Eigenschaften eines Listener-Objektes der OpenAL. Welche Eigenschaft gesetzt wird, hängt vom Wert für param ab.

Folgende Werte sind für param zulässig:

AL_GAIN

Setzt den skalaren Amplitudenmultiplikator für das Listener-Objekt. Der Vorgabewert 1.0 bedeutet, dass die Geräusche ungedämpft sind. Ein Wert von 0.5 ist äquivalent zu einer Abschwächung von 6 dB. Der Wert null entspricht Stille. Der AL_GAIN-Wert des Listener-Objektes wird zudem auf alle Source-Objekte im aktuellen Kontext angewendet (allerdings erst nachdem der AL_GAIN-Wert des jeweiligen Source-Objektes angewendet wurde.) Die OpenAL-Implementierung ist dafür verantwortlich, artefaktfreie (klickfreie) Änderungen des Wertes sicherzustellen und kann daher die tatsächliche Änderung (innerhalb gewisser akzeptabler Grenzen) verzögern. Als AL_GAIN-Wert ist jeder Wert größer oder gleich null zulässig. Jedoch kann die Implementierung den Wert in so einem Fall auf 1,0 absenken, um einen Wertüberlauf zu vermeiden. AL_GAIN ist nur für die Funktionsvarianten alListenerf und alListenerfv als Parameter zugelassen.

AL_ORIENTATION

Setzt die Orientiertheit des Listener-Objektes. Diese ist ein Paar aus 3-Tupeln (d.h. sechs Einzelwerte), welches aus einem "at"-Vektor und einem "up"-Vektor besteht. Beide Vektoren sollten linear unabhängig sein (d.h. sie sind nich parallel zueinander), jedoch müssen sie nicht notwendigerweise normalisiert sein. Der "at"-Vektor repräsentiert die nach vorn zeigende Richtung des Listener-Objektes, und die orthogonale Projektion des "up"-Vektors in den Unterraum senkrecht zum "at"-Vektor repräsentiert die "nach oben"-Richtung des "up"-Vektors. (Im Fall, dass der "up"-Vektor senkrecht auf dem "at"-Vektor steht, ist diese Projektion mit dem "up"-Vektor identisch.) Sollten der angegebene "up"- und der "at"-Vektor linear abhängig sein, so ist das Verhalten der OpenAL undefiniert. Der Standartwert ist ((0.0, 0.0, -1.0), (0.0, 1.0, 0.0)). Zulässig sind alle Werte außer NaN. AL_ORIENTATION ist nur für die Funktionsvarianten alListenerfv und alListeneriv als Parameter zulässig.

AL_POSITION

Setzt die aktuelle Position des Listener-Objektes. Der Standardwert ist (0.0, 0.0, 0.0); zulässig sind alle Werte außer NaN. AL_POSITION darf nur in den Funktionsvarianten alListener3f, alListenerfv, alListener3i und alListeneriv als Parameter verwendet werden.

AL_VELOCITY

Setzt die Geschwindigkeit (Schnelligkeit und Richtung) des Listener-Objektes im Koordinatensystem. Die Geschwindigkeit beeinflußt jedoch nicht die Position des Objektes. OpenAL berechnet die Geschwindigkeit nicht aus aufeinanderfolgenden Änderungen mit AL_POSITION, ebenso wenig wird die Position des Objektes über die Zeit anhand der angegebenen Geschwindigkeit angepasst. Alle diese Berechnungen muss die jeweilige Anwendung selbst übernehmen. Für die Belange der Soundverarbeitung sind Position und Geschwindigkeit unabhängige Parameter, die verschiedene Aspekte des Klangs auswirken. Die Geschwindigkeit spielt z.B. bei der Berechnung des Dopplereffektes eine Rolle. Der Standardwert ist (0.0, 0.0, 0.0); zulässig sind alle Werte außer NaN. AL_VELOCITY ist nur für alListenerfv, alListener3f, alListeneriv und alListener3i als Parameter zulässig.

Hinweise

Für die Funktionsvariante alListeneri sind in der Spezifikation von OpenAL 1.1 keine Listener-Eigenschaften definiert, die gesetzt werden könnten. Jedoch könnte die Funktion von einer OpenAL-Erweiterung benutzt werden.

Im Gegensatz zu anderen ähnlichen Funktionen wie alBuffer oder alSource, wo noch das jeweilige Puffer- oder Source-Objekt als Parameter angegeben werden muss, ist dies hier nicht notwendig, da innerhalb eines Kontexts auch immer nur ein einziges Listener-Objekt existiert.

Falls bei der Ausführung ein Fehler auftritt, kann dieser mit alGetError abgefragt werden.

Änderungen

Folgende Erweiterungen hat die Funktion erfahren:

Ab OpenAL-Version 1.1

Seit OpenAL 1.1 sind die Funktionsvarianten alListener3i und alListeneriv verfügbar.

Fehlermeldungen

AL_INVALID_ENUM wird generiert, wenn der angegebene Parameter unzulässig ist.

AL_INVALID_OPERATION wird generiert, falls es keinen aktuellen Kontext gibt. (Siehe auch alcMakeContextCurrent.)

AL_INVALID_VALUE wird generiert, sofern der angegebene Wert, auf welchen die Listener-Eigenschaft gesetzt werden soll, nicht zulässig ist. Im Fall von alListeneri und alListenerf betrifft das den Wert value, im Fall der Funktionsvarianten für Vektorwerte (alListenerfv und alListeneriv) betrifft dies den Werte, auf welche der Zeiger values zeigt, und im Fall der Funktionsvarianten für drei Wertargumente, alListener3f und alListener3i, ist mindestens einer der Werte v1, v2 oder v3 betroffen.

Zugehörige Wertrückgaben

alGetListener mit Token AL_GAIN
alGetListener mit Token AL_ORIENTATION
alGetListener mit Token AL_POSITION
alGetListener mit Token AL_VELOCITY

Siehe auch

alGetListener