alGetListener

alGetListener

Name

alGetListener - Liefert Eigenschaften eines Listener-Objektes der OpenAL zurück.

Delphi-Spezifikation

procedure alGetListenerf(param: TALenum; value: PALfloat);
procedure alGetListener3f(param: TALenum; v1: PALfloat; v2: PALfloat; v3: PALfloat);
procedure alGetListenerfv(param: TALenum; values: PALfloat);
procedure alGetListeneri(param: TALenum; value: PALint);
procedure alGetListener3i(param: TALenum; v1: PALint; v2: PALint; v3: PALint);
procedure alGetListeneriv(param: TALenum; values: PALint);

Parameter

param	Symbolische Konstante, welche den abzufragend Wert bestimmt
value	Zeiger auf den TALfloat-/ TALint-Wert, der zurückgegeben wird (nur bei alGetListenerf und alGetListeneri)
values	Zeiger auf einen TALfloat-/ TALint-Vektor, in welchem die zurückgegebenen Werte abgelegt werden (nur bei alGetListenerfv und alGetListeneriv)
v1, v2, v3	Zeiger auf TALfloat-/ TALint-Werte, in welchen die zurückgegebenen Werte abgespeichert werden (nur bei alGetListener3f und alGetListener3i)

Beschreibung

Die Funktion alGetListener bzw. ihre Varianten für verschiedene Wertargumente liefern Attribute eines Listener-Objektes der AL zurück. Welches Attribut genau zurückgeliefert wird, hängt vom Parameter param ab.

Folgende Werte sind für den Parameter param zulässig:

AL_GAIN

Gibt den skalaren Amplitudenmultiplikator für das Listener-Objekt zurück. 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 nachdem der AL_GAIN-Wert des jeweiligen Source-Objektes angewendet wurde.) AL_GAIN ist nur für die Funktionsvarianten alGetListenerf und alGetListenerfv als Parameter zugelassen.

AL_ORIENTATION

Gibt ein Paar aus 3-Tupeln zurück (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.) AL_ORIENTATION ist nur für die Funktionsvarianten alGetListenerfv und alGetListeneriv als Parameter zulässig.

AL_POSITION

Gibt die aktuelle Position des Listener-Objektes zurück. Der Standardwert ist (0.0, 0.0, 0.0). AL_POSITION darf nur in den Funktionsvarianten alGetListener3f, alGetListenerfv, alGetListener3i und alGetListeneriv als Parameter verwendet werden.

AL_VELOCITY

Gibt die Geschwindigkeit (Schnelligkeit und Richtung) des Listener-Objektes im Koordinatensystem zurück. 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. AL_VELOCITY ist nur für alGetListenerfv, alGetListener3f, alGetListeneriv und alGetListener3i als Parameter zulässig.

Hinweise

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

Im Gegensatz zu anderen ähnlichen Funktionen wie alGetBuffer oder alGetSource, wo noch das jeweilige Puffer- oder Source-Objekt als Parameter übermittelt 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 alGetListener3i und alGetListeneriv verfügbar.

Fehlermeldungen

AL_INVALID_ENUM wird generiert, wenn der angegeben Wert des Parameters param unzulässig ist.

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

AL_INVALID_VALUE wird generiert, sofern der Wertezeiger ungültig ist. Im Fall von alGetListeneri und alGetListenerf betrifft das den Zeiger value, im Fall der Funktionsvarianten für Vektorwerte (alGetListenerfv und alGetListeneriv) betrifft dies den Zeiger values und im Fall der Funktionsvarianten für drei Wertargumente, alGetListener3f und alGetListener3i, ist mindestens einer der Zeiger v1, v2 oder v3 betroffen.

Siehe auch

alListener