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_BYTE_OFFEST

Legt die Abpspielposition, ausgedrückt in Bytes, fest. Für Source-Objekte im Zustand AL_LOOPING wird dieser Wert wieder auf null zurückspringen, sobald die Wiedergabe wieder von vorn beginnt. Im Falle eines komprimierten Audioformates kann es sein, dass dieser Wert nur einen genäherten Wert innerhalb der komprimierten Daten angibt. Wird das Offset für ein Source-Objekt gesetzt, welches gerade Audiodaten abspielt, springt die Wiedergabe zur neuen Position, es sei denn der angegebene Wert ist außerhalb des zulässigen Bereichs, wodurch ein AL_INVALID_VALUE-Fehler generiert wird. Falls das Source-Objekt gerade keine Audiodaten abspielt, wird die Offsetänderung beim nächsten zugehörigen Aufruf von alSourcePlay durchgeführt. Ein Aufruf von alSourceStop, alSourceRewind oder ein zweiter Aufruf von alSourcePlay setzt das Offset zurück auf den Anfang des Puffers. Die Position ist relativ zum Anfang aller dem Source-Objekt angehängten Puffer, und jeder Puffer, der beim Setzen des Offsets traversiert wird, wird als verarbeitet (siehe alGetSource mit Token AL_BUFFERS_PROCESSED) markiert. Zulässige Werte sind Werte größer oder gleich null, ein Vorgabewert ist nicht festgelegt. AL_BYTE_OFFSET ist nur für die Funktionsvarianten alSourcef, alSourcefv, alSourcei und alSourceiv zulässig.

AL_CONE_INNER_ANGLE

(unvollständig)

AL_CONE_OUTER_ANGLE

(unvollständig)

AL_CONE_OUTER_GAIN

(unvollständig)

AL_DIRECTION

Legt die Ausrichtung eines Source-Objektes fest. Falls der AL_DIRECTION-Wert ungleich dem Nullvektor ist, so handelt es sich um ein gerichtetes Source-Objekt. Die Geräuschemission wird als symmetrisch um den Richtungsvektor herum angenommen (Zylindersymmetrie). Der Nullvektor ist der Vorgabewert, wodurch angegeben wird, dass das Source-Objekt nicht gerichtet ist. Das Setzen eines vom Nullvektor verschiedenen, dreidimensionalen Vektors macht aus dem Source-Objekt ein gerichtetes Objekt; das Setzen des Nullvektors für ein gerichtetes Source-Objekt macht es zu einem ungerichteten Source-Objekt. Zulässig sind alle Werte außer NaN. Der Parameter AL_DIRECTION ist nur für die Funktionsvarianten alSourcefv, alSource3f, alSourceiv und alSource3i zulässig.

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

AL_REFERENCE_DISTANCE beschreibt den Abstand, bei dem der Verstärkungsfaktor der Audioquelle genau 1 beträgt.

AL_ROLLOFF_FACTOR

(unvollständig)

AL_SAMPLE_OFFSET

Legt die Abspielposition fest, wobei diese Position in Samples ausgedrückt wird. Für Source-Objekte im Zustand AL_LOOPING wird dieser Wert wieder auf null zurückspringen, sobald die Wiedergabe wieder von vorn beginnt. Bei Verwendung eines komprimierten Formates gibt dieser Wert das exakte Offset innerhalb der unkomprimierten Daten an. Wenn AL_SAMPLE_OFFSET für ein Source-Objekt, welches gerade Audiodaten abspielt, gesetzt wird, so springt die Wiedergabe zur angegebenen Position, es sei denn das neue Offset ist außerhalb des zulässigen Bereiches, wodurch ein AL_INVALID_VALUE-Fehlerstatus generiert wird. Falls das Source-Objekt gerade keine Audiodaten abspielt, wird die Offsetänderung beim nächsten zugehörigen Aufruf von alSourcePlay durchgeführt. Ein Aufruf von alSourceStop, alSourceRewind oder ein zweiter Aufruf von alSourcePlay setzt das Offset zurück auf den Anfang des Puffers. Die Position ist relativ zum Anfang aller dem Source-Objekt angehängten Puffer, und jeder Puffer, der beim Setzen des Offsets traversiert wird, wird als verarbeitet (siehe alGetSource mit Token AL_BUFFERS_PROCESSED) markiert. Zulässige Werte sind alle Werte größer oder gleich null, ein Vorgabewert ist nicht festgelegt. AL_SAMPLE_OFFSET ist nur für die Funktionsvarianten alSourcef, alSourcefv, alSourcei und alSourceiv zulässig.

AL_SEC_OFFSET

Legt die Abspielposition fest, wobei diese Position in Sekunden ausgedrückt wird. Für Source-Objekte im Zustand AL_LOOPING wird dieser Wert wieder auf null zurückspringen, sobald die Wiedergabe wieder von vorn beginnt. Wenn AL_SEC_OFFSET für ein Source-Objekt, welches gerade Audiodaten abspielt, gesetzt wird, so springt die Wiedergabe zur angegebenen Position, es sei denn das neue Offset ist außerhalb des zulässigen Bereiches, wodurch ein AL_INVALID_VALUE-Fehlerstatus generiert wird. Falls das Source-Objekt gerade keine Audiodaten abspielt, wird die Offsetänderung beim nächsten zugehörigen Aufruf von alSourcePlay durchgeführt. Die Position ist relativ zum Anfang aller dem Source-Objekt angehängten Puffer, und jeder Puffer, der beim Setzen des Offsets traversiert wird, wird als verarbeitet (siehe alGetSource mit Token AL_BUFFERS_PROCESSED) markiert. Der Wert basiert auf der Byteposition, sodass ein mit AL_PITCH verändertes Source-Objekt eine überspitzte Abspielgeschwindigkeit hat. Zum Beispiel kann ein Puffer ein Offset von 0,50 Sekunden haben, jedoch dauert es nur 0,25 Sekunden, dahin zu gelangen, wenn der AL_PITCH-Wert auf 2,0 gesetzt ist. Für das Setzen des Offsets ist jeder Wert größer gleich 0,0 zulässig, ein Vorgabewert ist nicht definiert. Der Parameter AL_SEC_OFFSET ist nur für die Funktionsvarianten alSourcef, alSourcefv, alSourcei und alSourceiv zulässig.

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.

Ebenso sind die Token AL_BYTE_OFFSET, AL_SAMPLE_OFFSET und AL_SEC_OFFSET erst ab Version 1.1 verfügbar. Jedoch gibt es dafür auch die OpenAL-Erweiterung AL_EXT_OFFSET, welche von jeder Implementation der Open AL 1.1 unterstützt wird und es einer für die Spezifikation von OpenAL 1.0 geschriebenen aber auf eine Implementation der Version 1.1 zugreifenden Anwendung erlaubt, die drei genannten Tokenwerte auch zum Setzen (und Abfragen) der entsprechenden Werte zu nutzen.

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)