Dokumentation        Tutorials        Framework-Header

OpenAL Audio Framework – Dokumentation

Lizenz

Das hier vorliegende OpenAl Audio Framework steht unter der GNU LESSER GENERAL PUBLIC LICENSE (Version 3).



Initialisierung

Alle globalen Audio-Einstellungen sind in der Datei AudioSettings.txt abgespeichert, die im Zuge der Initialisierung des Audio Frameworks ausgelesen wird.


AudioSettings.txt:

#IDOfDevice(default=-1):# 0

#Auf Windows Visa und Windows 7 Systemen sollte für IDOFDevice der Wert
0 verwendet werden. Sofern sich im Bin Verzeichnis der Anwendung (bzw. im
Verzeichnis mit den ausführbaren Dateien) die Datei
soft_oal.dll befindet,
(siehe http://kcat.strangesoft.net/openal.html) werden alle Audioeffekte
(ähnlich wie bei XAudio2) komplett in Software berechnet,
wodurch der Wegfall des Generic Hardware Device (XP) vollständig
kompensiert wird#

#Max3DSoundDistanceSq:# 10000.0
#MaxImmediate3DSoundDistanceSq:# 10000.0

#Die DistanceSq-Parameter haben keinen direkten Einfluss auf die
Soundeffekte. Jedoch lässt sich mit ihrer Hilfe entscheiden, ob und wie
ein Soundeffekt abgespielt werden soll. Ist die Soundquelle bsp. zu weit
von der Kamera (bzw. dem Zuhörer/Listener) entfernt, kann auf ein Abspielen
verzichtet werden.

Soll ein Soundeffekt im Modus "Immediate" abgespielt werden,
dann wird ein anderer aktiver Soundeffekt unterbrochen, falls momentan
keine freie Soundquelle zur Verfügung steht!!#


#Lautstärkeregelung – anfängliche Einstellungen:#

#EffectVolume:#  2.0
#MusicVolume:#  0.25
#VoiceVolume:#  1.0

#DistanceModel:# 2

#
Distance-Modelle beschreiben die Abnahme der Schallintensität mit
zunehmender Entfernung vom Listener:

AL_INVERSE_DISTANCE=0
AL_INVERSE_DISTANCE_CLAMPED=1
AL_LINEAR_DISTANCE=2
AL_LINEAR_DISTANCE_CLAMPED=3
AL_EXPONENT_DISTANCE=4
AL_EXPONENT_DISTANCE_CLAMPED=5
#


#Einfluss der relativen Geschwindigkeit zwischen Soundquelle und
Listener auf das Klangbild eines Soundeffekts (Doppler Effekt):#

#DopplerFactor:# 1.0

#EnableEFXReverbEffects: (no=0,yes=1):# 1

#EFX ist vergleichbar mit EAX (Environmental Audio Extensions) und
berücksichtigt die Umgebungseinflüsse auf das Klangbild eines Soundeffekts.
Es ist jedoch besser an die OpenAL-API angepasst und lässt sich
zudem plattformunabhängig einsetzen!#


#IDOfInitialUsedEAXFilter:# 90

#
Filter:
REVERB_PRESET_GENERIC                    0
REVERB_PRESET_PADDEDCELL                 1
REVERB_PRESET_ROOM                       2

[...]
#


3D-Soundeffekte

Die für die Ausgabe von 3D-Soundeffekten benötigten Daten müssen im wav-Format vorliegen und werden permanent im Speicher gehalten (statische Sounds). Zwar lassen sich wav-Dateien auch einzeln laden, jedoch ist dieses Vorgehen für den praktischen Einsatz nur bedingt zu empfehlen. Vielmehr sollten Sie eine Liste mit allen benötigten Soundeffekten erstellen (siehe SoundEffects.txt) und diese in einem Zug einlesen.

Hinweis:
3D-Soundeffekte werden in einem separaten Thread geladen, damit andere Programmfunktionen wegen der relativ langsamen Festplattenzugriffe nicht ausgebremst werden.

SoundEffects.txt:

NumSoundEffects: 2

0, DistantCollision1.wav
NumSources: 5
MaxDistance: 60.0
Gain: 1.0
RollOff: 1.0
PlayLoop(no=0,yes=1): 0

1, DistantCollision2.wav
NumSources: 5
MaxDistance: 60.0
Gain: 1.0
RollOff: 1.0
PlayLoop(no=0,yes=1): 0


Erläuterungen:

  • NumSources: Anzahl der Soundquellen, die den betreffenden Sound parallel abspielen können
  • MaxDistance: maximale Distanz, innerhalb derer der Sound noch hörbar ist
  • Gain: Intensität des Soundeffekts (Lautstärke)
  • RollOff: Intensitätsabnahme des Soundeffekts mit zunehmender Entfernung entsprechend des verwendeten Distanzmodells
  • PlayLoop: Legt fest, ob ein Soundeffekt in einer Endlosschleife abgespielt werden soll


Musikstücke

Musikstücke (wahlweise im ogg- bzw. wav-Format) werden schrittweise in einem separaten Thread eingelesen und abgespielt (Streaming). Die Dateinamen der abzuspielenden Musikstücke lassen sich einzeln oder in Form einer Track-List einlesen:

MusicTracks.txt:

NumMusicTracks: 2

0, Sample1.ogg
1, Sample2.wav


Hinweis:
Aktuell lassen sich bis zu 4 Musikstücke parallel abspielen.


Voice Samples (Sprachausgabe)

Voice Samples (wahlweise im ogg- bzw. wav-Format) werden schrittweise in einem separaten Thread eingelesen und abgespielt (Streaming). Die Dateinamen der abzuspielenden Samples lassen sich einzeln oder in Form einer Sample-List einlesen:

VoiceSamples.txt:

NumVoiceSamples: 2

0, Sample1.ogg
1, Sample2.wav


Hinweis:
Aktuell lassen sich bis zu 4 Voice Samples parallel abspielen.



Praktischer Einsatz des Frameworks


Nachfolgend werden einige Anwendungsbeispiele betrachtet, damit sich der praktische Einsatz des Frameworks besser nachvollziehen lässt:

Initialisierung bei Programmstart:

Load_SoundSettings_And_Init_Audio("AudioSettings.txt");


Aufräumarbeiten bei Programmende:

Shutdown_Audio();


Einzelne 3D-Soundeffekte laden:

// Soundeffekte einzeln laden:
Set_MaxNumberOfSoundEffects(10);

Add_New_SoundEffect(0, "../SoundAndMusic/DistantCollision1.wav",
                    5, 60.0f, 1.0f, 1.0f, 0);
Add_New_SoundEffect(1, "../SoundAndMusic/DistantCollision2.wav",
                    5, 60.0f, 1.0f, 1.0f, 0);


Einzelne 3D-Soundeffekte entladen:

Unload_SoundEffect(0);
Unload_SoundEffect(1);


Eine Liste mit 3D-Soundeffekten laden:

Load_SoundEffectList("../SoundAndMusic/SoundEffects.txt",
                     "../SoundAndMusic/");


Einen 3D-Soundeffekt abspielen:

if(absDistance < g_Max3DSoundDistance)
{
if(absDistance < g_MaxImmediate3DSoundDistance)
{
    SoundEffectID = lrnd(0, 2);
    SourceID = Play_SoundEffect_Immediately(&g_matView, SoundEffectID,
               &Asteroid[Asteroid_ID2].CameraSpacePosition,
               &g_NullVector, true /*Reverb*/);
}
else
{
    SoundEffectID = lrnd(0, 2);
    SourceID = Play_SoundEffect(&g_matView, SoundEffectID,
               &Asteroid[Asteroid_ID2].CameraSpacePosition,
               &g_NullVector, true /*Reverb*/);
}
}


Einen 3D-Soundeffekt von einer ganz bestimmten Soundquelle abspielen:

Play_SoundEffect_Immediately(2 /*SoundEffectID*/, 0 /*SourceID*/,
                             true /*Reverb*/);

Play_SoundEffect_Immediately(&g_matView, 2 /*SoundEffectID*/,
                             0 /*SourceID*/,
                             &SourcePosition,
                             &SourceVelocity, true /*Reverb*/);

Play_SoundEffect_Immediately(2 /*SoundEffectID*/,
                             0 /*SourceID*/,
                             &SourcePosition,
                             &SourceVelocity, true /*Reverb*/);


Position und Geschwindigkeit eines 3D-Soundeffekts (bzw. der zugehörigen Soundquelle) aktualisieren:

Update_SoundEffect_Position(&g_matView, 2 /*SoundEffectID*/, 0 /*SourceID*/,
                            &SourceCameraSpacePosition);

Update_SoundEffect_Velocity(&g_matView, 2
/*SoundEffectID*/, 0 /*SourceID*/,
                            &SourceVelocity);


Tonhöhe eines 3D-Soundeffekts modulieren:

Set_SoundEffect_Pitch(1.2f, /* > 1.0 := höher; < 1.0 := tiefer*/
                      2 /*SoundEffectID*/, 0 /*SourceID*/);


Abspielen eines 3D-Soundeffekts beenden:

Stop_SoundEffect_Immediately(2 /*SoundEffectID */, 0 /*SourceID*/);


Eine Liste von Musikstücken laden und mit dem Abspielen eines zufälligen Musikstücks beginnen:

MusicTracks = new CMusicTracks;
MusicTracks->Load_TrackList("../SoundAndMusic/MusicTracks.txt",
                            "../SoundAndMusic/");

MusicTracks->Start_RandomMusicTrack();


Zwei Musikstücke parallel abspielen:

// nur sinnvoll, wenn sich beide Tracks mischen lassen!
MusicTracks->Start_MusicTrack(0, 0 /*StreamID*/);
MusicTracks->Start_MusicTrack(1, 1 /*StreamID*/);


Hintergrundmusik aktualisieren (neuen Titel abspielen, wenn aktueller Titel beendet ist):

MusicTracks->Update();


Eine Liste von Sprach-Samples für die Sprachausgabe laden:

VoiceSamples = new CVoiceSamples;
VoiceSamples->Load_SampleList("../SoundAndMusic/VoiceSamples.txt",
                              "../SoundAndMusic/");


Mit dem Abspielen eines Sprach-Samples beginnen:

// Position des Sprechers aktualisieren:
Update_VoiceStream_Position(&g_matView, &CameraSpacePosition,
                            0, /*StreamID*/);

VoiceSamples->Start_Sample(0);


Zwei Sprach-Samples parallel abspielen:

VoiceSamples->Start_Sample(0, 0 /*StreamID*/);
VoiceSamples->Start_Sample(1, 1 /*StreamID*/);