alSource

Hinweis: Dieser Artikel ist noch unvollständig. (Mehr Informationen/weitere Artikel) Die Beschreibung zu den Auswirkungen des Funktionsparameters param muss noch ergänzt werden. Als Grundlage kann die Open AL-Dokumentation dienen.

---

alSource

Name

alSource - Setzt Eigenschaften eines Source-Objektes.

Delphi-Spezifikation

procedure alSourcef(source: TALuint; param: TALenum; value: TALfloat);
procedure alSource3f(source: TALuint; param: TALenum; v1: TALfloat; v2: TALfloat; v3: TALfloat);
procedure alSourcefv(source: TALuint; param: TALenum; values: PALfloat);
procedure alSourcei(source: TALuint; param: TALenum; value: TALint);
procedure alSource3i(source: TALuint; param: TALenum; v1: TALint; v2: TALint; v3: TALint);
procedure alSourceiv(source: TALuint; param: TALenum; values: PALint);

Parameter

source	Name des Source-Objektes, dessen Eigenschaft geändert werden soll
param	Symbolische Konstante, welche die zu setzende Eigenschaft angibt
value	TALfloat-/ TALint-Wert, der gesetzt werden soll (nur bei alSourcef bzw. alSourcei)
values	Zeiger auf einen TALfloat-/ TALint-Vektor, welcher die zu setzenden Werte enthält (nur bei alSourcefv und alSourceiv)
v1, v2, v3	TALfloat-/ TALint-Werte, welche die zu setzenden Werte angeben (nur bei alSource3f und alSource3i)

Beschreibung

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

Folgende Werte sind für param zulässig:

AL_BUFFER

Legt den aktuellen Puffer fest und macht ihn zum ersten Eintrag in der Pufferwarteschlange des Source-Objektes. Der Vorgabewert ist AL_NONE, zulässige Werte sind alle gültigen Puffernamen (siehe dazu auch alIsBuffer). Wird alSource mit dem Parameter AL_BUFFER auf ein Source-Objekt im Zustand AL_INITIAL oder AL_STOPPED angewendet, so wird die gesamte Pufferwarteschlange geleert und der angegebene Puffer an das Source-Objekt angehangen.

Für ein Source-Objekt im Zustand AL_PLAYING oder AL_PAUSED wird der Versuch, mit AL_BUFFER einen Wert zu setzen, den Fehlerstatus AL_INVALID_OPERATION setzen. AL_BUFFER kann nur auf Source-Objekte im Zustand AL_STOPPED oder AL_INITIAL angewendet werden. Die Angabe eines ungültigen Puffernamens, sei es weil dieser Puffer nicht existiert oder nicht an das Source-Objekt angehängt werden kann, setzt den Fehlerstatus AL_INVALID_VALUE, während die Angabe eines ungültigen Source-Objektes den Fehlerstatus AL_INVALID_NAME zur Folge hat.

AL_NONE (nil oder 0) ist ein gültiger Puffername. Der Aufruf alSourcei(sourceName, AL_BUFFER, AL_NONE) ist eine zulässige Möglichkeit, die aktuelle Pufferwarteschlange eines Source-Objektes freizugeben, egal ob die Pufferwarteschlange nur einen Eintrag (den aktuellen Puffer) oder mehrer hat. Jedoch verursacht der Funktionsaufruf alSourcei(sourceName, AL_BUFFER, AL_NONE) immer noch einen AL_INVALID_OPERATION-Fehlerstatus für ein im Zustand AL_PLAYING oder AL_PAUSED befindliches Source-Objekt und kann folgerichtig nicht genutzt werden, um ein Source-Objekt anzuhalten (siehe dazu alSourceStop) oder stummzuschalten. Der Paramater AL_BUFFER ist nur für die Funktionsvarianten alSourcei und alSourceiv zugelassen.

AL_CONE_INNER_ANGLE

(unvollständig)

AL_CONE_OUTER_ANGLE

(unvollständig)

AL_CONE_OUTER_GAIN

(unvollständig)

AL_DIRECTION

(unvollständig)

AL_GAIN

Legt den skalaren Amplitudenmultiplikator für das Source-Objekt fest. 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. Die Implementierung ist dafür verantwortlich, artefaktfreie (d.h. klickgeräuschfreie) Änderungen des Wertes zu ermöglichen und kann daher die tatsächliche Änderung des Wertes innerhalb gewisser, akzeptabler Grenzen verzögern. Werte größer als eins sind zwar zulässig, jedoch steht es der Implementierung frei, Werte größer als 1,0 auf 1,0 herunterzuregeln, um einen möglichen Überlauf zu vermeiden. AL_GAIN ist nur für die Funktionsvarianten alSourcef und alSourcefv zulässig.

AL_LOOPING

Legt fest, ob das Source-Objekt nicht in den Zustand AL_STOPPED wechselt, sobald es das Ende des letzten Puffers in der Pufferwarteschlange erreicht hat. In diesem Fall ist der Wert AL_TRUE zu setzen, andernfalls AL_FALSE. Der Vorgabewert für AL_LOOPING ist AL_FALSE. Ist das AL_LOOPING-Flag auf AL_TRUE gesetzt, so wechselt das Source-Objekt beim Erreichen des Endes der Pufferwarteschlange sofort wieder in den Zustand AL_INITIAL und danach in den Zustand AL_PLAYING, um die Audiodaten in den zugehörigen Puffern erneut abzuspielen. Das AL_LOOPING-Flag für ein Source-Objekt kann in jedem Ausführungszustand, besonders auch im Zustand AL_PLAYING, geändert werden. Zulässige Werte sind AL_TRUE und AL_FALSE. Der Paramater AL_LOOPING ist nur für die Funktionsvarianten alSourcei und alSourceiv als Paramater zugelassen.

AL_MAX_DISTANCE

(unvollständig)

AL_MAX_GAIN

Setzt den maximalen, erlaubten AL_GAIN-Wert für das Source-Objekt. Der Vorgabewert ist 1.0, zulässig sind alle Gleitkommawerte aus dem Intervall von 0,0 bis 1,0. Am Ende der Varabrebitung verschiedener Abschwächungs- oder Verstärkungsfaktoren wie der entfernungsbasierten Abschwächung und dem AL_GAIN-Wert des Source-Objektes wird der berechnete Effektivwert mit dem AL_MAX_GAIN-Wert verglichen. Falls der berechnete Wert größer ist als der AL_MAX_GAIN-Wert, dann wird der AL_MAX_GAIN-Wert angewendet. Dies geschieht jedoch, bevor der AL_GAIN-Wert des Listener-Objektes in Betracht gezogen wird. Wenn das Produkt aus AL_MAX_GAIN und dem AL_GAIN-Wert des Listener-Objektes immer noch den maximalen Wert, welchen die Implementierung handhaben kann, überschreitet, so steht es der Implementierung frei, den Wert zu reduzieren. Falls für AL_MAX_GAIN der Wert null gesetzt wird, so ist das Source-Objekt quasi stummgeschalten. Die vorgesehene Art, ein Source-Objekt stummzuschalten, ist jedoch, den AL_GAIN-Wert auf null zu setzen. Der Parameter AL_MAX_GAIN ist nur für die Funktionsvarianten alSourcef und alSourcefv zulässig.

AL_MIN_GAIN

Legt den minimalen AL_GAIN-Wert fest, welcher für das Source-Objekt immer gewährleistet sein soll. Der Vorgabewert ist 0.0, zulässig sind alle Werte aus dem Intervall von 0,0 bis 1,0. Am Ende der Verarbeitung verschiedener Abschwächungsfaktoren wie der entfernungsbasierten Abschwächung und dem AL_GAIN-Wertes des Source-Objektes wird der berechnete Effektivwert mit dem AL_MIN_GAIN-Wert verglichen. Falls der berechnete Wert kleiner ist als AL_MIN_GAIN, so wird der Wert von AL_MIN_GAIN angewendet. Dies passiert jedoch, bevor der AL_GAIN-Wert des Listener-Objektes angewendet wird. Wenn der für AL_MIN_GAIN gesetzte Wert null ist, so wird keine Korrektur vorgenommen. Der Parameter AL_MIN_GAIN ist nur für die Funktionsvarianten alSourcef und alSourcefv zugelassen.

AL_PITCH

Setzt die Verschiebung der Tonhöhe/ Frequenz des Source-Objektes. Ein Wert von 1,0 entspricht der Identität (d.h. keine Verschiebung), dies ist auch der Vorgabewert. Jede Reduzierung des Wertes um 50% entspricht einer Verschiebung um 12 Halbtöne bzw. eine Oktave nach unten. Jede Verdopplung des Wertes entspricht einer Verschiebung von 12 Halbtönen bzw. einer Oktave nach oben. Null ist kein zulässiger Wert, alle Gleitkommawerte größer als null sind erlaubt. Jede Implementierung kann die AL_PITCH-Werte aber entsprechend ihrer eigenen Limitationen beschränken. AL_PITCH ist nur für die Funktionsvarianten alSourcef und alSourcefv als Parameter zugelassen.

AL_POSITION

Setzt die aktuelle Position des Source-Objektes im Weltkoordinatensystem. Der Standardwert ist (0.0, 0.0, 0.0). AL_POSITION darf nicht in alSourcei oder alSourcef benutzt werden sondern nur in den Funktionsvarianten für mehrere Wertargumente, also alSource3f, alSource3i, alSourcefv oder alSourceiv. Erlaubt ist jedes Tripel von Fließkommawerten mit Ausnahme von NaN. Es ist nicht definiert, wie sich die Implementation verhält, falls NaN oder ein unendlicher Wert gesetzt wird.

AL_REFERENCE_DISTANCE

(unvollständig)

AL_ROLLOFF_FACTOR

(unvollständig)

AL_SOURCE_RELATIVE

Legt fest, ob die Position, Geschwindigkeit, Richtung und der Schallkegel relativ zum Listener-Objekt interpretiert werden oder nicht. Bei einem Wert von AL_TRUE sind die Angaben relativ zu sehen, bei AL_FALSE nicht. Vorgabewert ist AL_FALSE. AL_SOURCE_RELATIVE ist nur für die Funktionsvarianten alSourcei und alSourceiv als Parameterwert zulässig.

AL_SOURCE_STATE

(unvollständig)

AL_VELOCITY

Setzt die Geschwindigkeit (Schnelligkeit und Richtung) des Source-Objektes im Koordinatensystem. Jedes Tripel aus gültigen Gleitkommawerten ist erlaubt, abgesehen von NaN. Der Vorgabewert ist (0.0, 0.0, 0.0). 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. Jede derartige Berechnung bleibt der Anwendung überlassen. Für die Belange der Soundverarbeitung sind Position und Geschwindigkeit unabhängige Parameter, die sich auf verschiedene Aspekte des Klangs auswirken. AL_VELOCITY wird von Treiber berücksichtigt, um den vom Hörer wahrgenommenen Dopplereffekt zu berechnen, was auf Grundlage der Geschwindigkeit des Source-Objektes, des Listener-Objektes und der dopplereffektbezogenen Paramater geschieht. AL_VELOCITY ist nur für die Funktionsvarianten alSourcefv, alSource3f, alSourceiv und alSource3i als Paramater zulässig.

Hinweise

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

Änderungen

Folgende Erweiterungen hat die Funktion erfahren:

Ab OpenAL-Version 1.1

Seit OpenAL-Version 1.1 existieren auch die Funktionen für mehrere Ganzzahlwerte, alSource3i und alSourceiv.

Fehlermeldungen

AL_INVALID_ENUM wird generiert, wenn der Wert für param unzulässig ist.

AL_INVALID_NAME wird generiert, sofern source kein gültiges Source-Objekt ist. (Siehe auch alIsSource.)

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

AL_INVALID_VALUE wird generiert, wenn der zu setzenden Wert den zulässigen Bereich überschreitet.

Zugehörige Wertrückgaben

alGetSource mit den oben genannten Tokenwerten liefert die gesetzten Werte zurück.

Siehe auch

alGetSource, alListener (analoge Funktion für Listener-Objekte)