Version vom 14. Mai 2008, 19:07 Uhr

Hinweis: Dieser Artikel ist noch unvollständig. (Mehr Informationen/weitere Artikel) {{{1}}}

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

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

(unvollständig)

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

(unvollständig)

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)