alGetSource

Hinweis: Dieser Artikel ist noch unvollständig. (Mehr Informationen/weitere Artikel) Beschreibung zu den einzelnen Werten von param ist noch nicht fertiggestellt und bedarf mehrerer Ergänzungen. Siehe auch Open AL-Dokumentation (englisch).

---

alGetSource

Name

alGetSource - Liefert Eigenschaften eines Source-Objektes von OpenAL.

Delphi-Spezifikation

procedure alGetSource3f(source: TALuint; param: TALenum; v1: PALfloat; v2: PALfloat; v3: PALfloat);
procedure alGetSourcef(source: TALuint; param: TALenum; value: PALfloat);
procedure alGetSourcefv(source: TALuint; param: TALenum; values: PALfloat);
procedure alGetSource3i(source: TALunit; param: TALenum; v1: PALint; v2: PALint; v3: PALint);
procedure alGetSourcei(source: TALunit; param: TALenum; value: PALint);
procedure alGetSourceiv(source: TALuint; param: TALenum; values: PALint);

Parameter

source	Source-Objekt, dessen Eigenschaft bestimmt werden soll
param	Symbolische Konstante, welche die zurückzugebende Eigenschaft bestimmt
value	Zeiger auf den TALfloat-/TALint-Wert, der zurückgegeben wird (nur bei alGetSourcef und alGetSourcei)
values	Zeiger auf einen TALfloat-/TALint-Vektor, in welchem die zurückgegebenen Werte abgelegt werden (nur bei alGetSourcefv und alGetSourceiv)
v1, v2, v3	Zeiger auf TALfloat-/TALint-Werte, in welchen die zurückgegebenen Werte abgespeichert werden (nur bei alGetSource3f und alGetSource3i)

Beschreibung

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

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

AL_BUFFER

Gibt den Namen des aktuellen Pufferobjektes an. AL_BUFFER ist nur für die Funktionsvarianten alGetSourcei und alGetSourceiv zulässig.

AL_BUFFERS_PROCESSED

Gibt die Anzahl der schon durch das Source-Objekt source abgespielten Puffer zurück. Bei einem Source-Objekt im Zustand AL_STOPPED sind alle Puffer verarbeitet, bei einem Source-Objekt mit dem Zustand AL_INITIAL ist noch kein Puffer verarbeitet. Der Rückgabewert ist 0, wenn der gegenwärtige und einzige Puffer der Nullpuffer ist. AL_BUFFERS_PROCESSED ist nur für die Funktionsvarianten alGetSourcei und alGetSourceiv zulässig.

AL_BUFFERS_QUEUED

Gibt die Anzahl der an source angehängten Puffer zurück. Diese Zahl beinhaltet sowohl die Puffer, welche noch nicht abgespielt wurden, als auch den gegenwärtig abgespielten Puffer und die schon abgespielten Puffer. Der Rückgabewert ist 0, wenn der gegenwärtige und einzige Puffer der Nullpuffer ist. AL_BUFFERS_QUEUED ist nur für die Funktionsvarianten alGetSourcei und alGetSourceiv zulässig.

AL_BYTE_OFFSET

Gibt die Abspielposition, ausgedrückt in Bytes, an. 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. Die Position ist relativ zum Anfang aller dem Source-Objekt angehängten Puffer. AL_BYTE_OFFSET ist nur für die Funktionsvarianten alGetSourcef, alGetSourcefv, alGetSourcei und alGetSourceiv zulässig.

AL_CONE_INNER_ANGLE

(unvollständig)

AL_CONE_OUTER_ANGLE

(unvollständig)

AL_CONE_OUTER_GAIN

(unvollständig)

AL_DIRECTION

Gibt die Ausrichtung eines Source-Objektes an. 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. Der Parameter AL_DIRECTION ist nur für die Funktionsvarianten alGetSourcefv, alGetSource3f, alGetSourceiv und alGetSource3i zulässig.

AL_GAIN

Gibt den skalaren Amplitudenmultiplikator für das Source-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. AL_GAIN ist nur für die Funktionsvarianten alGetSourcef und alGetSourcefv zulässig.

AL_LOOPING

Gibt an, ob das Source-Objekt nicht in den Status AL_STOPPED wechselt, sobald es alle angehängten Puffer abgespielt hat. In diesem Fall ist der Rückgabewert AL_TRUE, andernfalls AL_FALSE. Ein Source-Objekt im Zustand AL_LOOPING wechselt, sobald es alle mit ihm verbundenen Puffer abgearbeitet hat, in den Zustand AL_INITIAL und danach in den Zustand AL_PLAYING, um dann die Pufferdaten wieder von vorn abzuspielen. Vorgabewert für AL_LOOPING ist AL_FALSE. AL_LOOPING ist nur für Aufrufe mit alGetSourcei und alGetSourceiv zulässig.

AL_MAX_GAIN

Gibt den maximalen AL_GAIN-Wert zurück, der für das Source-Objekt erlaubt ist. Am Ende der Verarbeitung verschiedener Abschwächungs-/ Verstärkungsfaktoren wie der entfernungsbasierten Anpassung und dem AL_GAIN-Wert des Source-Objektes wird der berechnete Wert mit dem Wert von AL_MAX_GAIN verglichen. Falls der berechnete Wert größer ist als der von AL_MAX_GAIN bestimmte Wert, wird der AL_MAX_GAIN-Wert verwendet. Dies geschieht, bevor die Abschwächungsfaktoren des Listener-Objekts einbezogen werden. Falls der Wert für AL_MAX_GAIN auf Null gesetzt wurde, ist das Source-Objekt praktisch stummgeschalten. AL_MAX_GAIN ist nur für die Funktionsvarianten alGetSourcef und alGetSourcefv zulässig.

AL_MAX_DISTANCE

(unvollständig)

AL_MIN_GAIN

Gibt den minimalen AL_GAIN-Wert zurück, der für das Source-Objekt immer gewährleistet wird. Am Ende der Verarbeitung verschiedener Abschwächungsfaktoren wie der entfernungsbasierten Abschwächung und dem AL_GAIN-Wert des Source-Objektes wird der berechnete Wert mit dem Wert von AL_MIN_GAIN verglichen. Falls der berechnete Wert geringer ist als der von AL_MIN_GAIN vorgegebene Wert, wird AL_MIN_GAIN-Wert angewendet. Dies passiert, bevor die Abschwächungsfaktoren durch das Listener-Objekt einbezogen werden. Falls der AL_MIN_GAIN-Wert null ist, wird keine Korrektur vorgenommen. AL_GAIN ist nur für die Funktionsvarianten alGetSourcef und alGetSourcefv als Parameter zulässig.

AL_PITCH

Gibt die Verschiebung der Tonhöhe/ Frequenz des Source-Objektes an, wobei ein Wert von 1.0 der Identität (d.h. keine Verschiebung) entspricht. Jede Verminderung des Wertes um 50% entspricht einer Tonhöhenverschiebung von 12 Halbtönen bzw. einer Oktave nach unten. Jede Verdopplung entspricht einer Verschiebung von 12 Halbtönen bzw. einer Oktave nach oben. AL_PITCH ist nur für die Funktionsvarianten alGetSourcef und alGetSourcefv zulässig.

AL_POSITION

Gibt die aktuelle Position des Source-Objektes zurück. Der Standardwert ist (0.0, 0.0, 0.0). AL_POSITION darf nicht in alGetSourcei oder alGetSourcef benutzt werden sondern nur in den Funktionsvarianten für mehrere Wertargumente, also alGetSource3f, alGetSource3i, alGetSourcefv oder alGetSourceiv.

AL_REFERENCE_DISTANCE

(unvollständig)

AL_ROLLOFF_FACTOR

(unvollständig)

AL_SAMPLE_OFFSET

Gibt die gegenwärtige Abspielposition an, 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. Die Position ist relativ zum Anfang aller dem Source-Objekt angehängten Puffer. AL_SAMPLE_OFFSET ist nur für die Funktionsvarianten alGetSourcef, alGetSourcefv, alGetSourcei und alGetSourceiv zulässig.

AL_SEC_OFFSET

Gibt die aktuelle Abspielposition an, 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. Die Position ist relativ zum Anfang aller dem Source-Objekt angehängten Puffer. 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 dauerte es nur 0,25 Sekunden, dahin zu gelangen, wenn der AL_PITCH-Wert auf 2,0 gesetzt ist. Der Parameter AL_SEC_OFFSET ist nur für die Funktionsvarianten alGetSourcef, alGetSourcefv, alGetSourcei und alGetSourceiv zulässig.

AL_SOURCE_RELATIVE

Gibt zurück, ob die Position, Geschwindigkeit und Richtung eines Source-Objektes relativ zur Position des Listener-Objektes interpretiert werden oder nicht. Falls dem so ist, wird AL_TRUE zurückgegeben, andernfalls AL_FALSE. Der Standardwert hierfür ist AL_FALSE. AL_SOURCE_RELATIVE ist nur für alGetSourcei und alGetSourceiv zulässig.

AL_SOURCE_STATE

Gibt den aktuellen Zustand des Source-Objektes zurück. Ein Source-Objekt kann folgende Zustände haben: AL_INITIAL, AL_PLAYING, AL_PAUSED oder AL_STOPPED. Um den Zustand zu ändern, können die Funktionen alSourcePlay, alSourcePause, alSourceStop und alSourceRewind genutzt werden. AL_SOURCE_STATE ist als Parameter nur für die Funktionsvariante alGetSourcei zulässig.

AL_SOURCE_TYPE

Gibt den Typ des Source-Objektes zurück. Mögliche Rückgabewerte sind AL_UNDETERMINED, AL_STATIC und AL_STREAMING. Der Standardwert hierfür ist AL_UNDETERMINED und alle Source-Objekte befinden sich direkt nach Erzeugung mit alGenSources in diesem Zustand.

Wenn ein Puffer mit dem Funktionsaufruf alSourcei(sourceID, AL_BUFFER, bufferID) an ein Source-Objekt angehängt wird, so ändert dieses Objekt seinen Typ zu AL_STATIC. Wird der erste Puffer hingegen durch alSourceQueueBuffers an ein Source-Objekt angehängt, so wechselt dieses seinen Typ zu AL_STREAMING. Der Versuch, den "Nullpuffer" durch den Aufruf alSourcei(source, AL_BUFFER, nil) an ein Source-Objekt anzuhängen, setzt den Typ des Source-Objektes auf AL_UNDETERMINED zurück, egal in welchem Zustand es vorher war; das Anhängen irgendeines anderen Puffers (außer dem Nullpuffer) versetzt das Source-Objekt in den Zustand AL_STATIC.

AL_SOURCE_TYPE ist nur für Aufrufe mit alGetSourcei und alGetSourceiv zulässig.

AL_VELOCITY

Gibt die Geschwindigkeit (Schnelligkeit und Richtung) des Source-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 sich auf verschiedene Aspekte des Klangs auswirken. Die Geschwindigkeit spielt z.B. bei der Berechnung des Dopplereffektes eine Rolle. AL_VELOCITY ist nur für alGetSourcefv, alGetSource3f, alGetSourceiv und alGetSource3i als Parameter zulässig.

Hinweise

Tritt bei der Ausführung ein Fehler auf, so lässt sich dieser mit alGetError abfragen.

Änderungen

Folgende Erweiterungen hat die Funktion erfahren:

Ab OpenAL-Version 1.1

Seit OpenAL 1.1 existiert die Funktion auch in den Ausprägungen für drei Fließkomma- bzw. Ganzzahlwerte, alGetSource3f bzw. alGetSource3i. Ebenso ist alGetSourceiv neu hinzugekommen.

Auch 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 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 die Wertezeiger unzulässig sind. Im Fall von alGetSourcei und alGetSourcef betrifft das den Zeiger value, im Fall der Funktionsvarianten für Vektorwerte (alGetSourcefv und alGetSourceiv) betrifft dies values und im Fall der Funktionsvarianten für drei Wertargumente, alGetSource3f und alGetSource3i, ist mindestens einer der Zeiger v1, v2 oder v3 betroffen.

Siehe auch

alSource