Audio Subsystem

Detailed Description

This section of the documentation covers Nebula audio system and it's subsystems.

Overview

The Nebula Audio System is consist of the following compenents:

Audio Serever
Listener
Sound
Sound Resource

Audio Server :

It is Nebula audio server to create and initialize sound device of the user system. An nAudioServer3 derived class implements does the actual specifics.

Note:: Not likely any other Nebula server, the audio server does not need to trigger. See Triggering Servers page for more details.

Listener :

A listener can be considered as a controller for 3D sound effects. Commonly, the 3D sound effects in a application are affected not only by the position, orientation and velocity values of the sound sources, but also by the position, orientation and velocity values of the virtual listener. See the nListener3 for more details.

Sound :

It is a sound parameter hold for a game entity. It is described as nSound3 class and its subclasses.

Sound Resource :

It is a container for a sound data. A sound data is format specific sound file like .wav, .ogg etc. It is described as nSoundResource class and its subclasses.

The most difference between 'Sound' and 'Sound Resource' is that the 'Sound' cannot be shared among the game entities but 'Sound Resource' can be. For an example, imagine that there are two soldiers as the game entity. Both soldiers have same rifle so they will play out same sound when they fire the rifle. To play the sound of the rifle, both soldier should have its own Sound object but the actual sound data both Sound objects refer is same Sound Resource cause they have same rifle. Though they play the same sound, the volume or orientation of the sound can be different by the position of the each soldiers. That is the reason why each of the game entity should have its own 'Sound' object.

Usage

This section of the documentation covers a brief usage of the Nebual audio system.

Audio Server Initialization

The audio server can be created from C++ or script code. The default location of the audio server is /sys/servers/audio.

    nDSoundServer3* audioServer = (nDSoundServer3*)kernelserver->New("ndsoundserver3", "/sys/servers/audio");

You can also create the audio server with tcl script like the following:

    new ndsoundserver3 /sys/servers/audio

With the above code sample, we created the instance of the nDSoundServer3 but you can use one of the other sound servers as well.

The next thing to do after the creation of the audio server is to initialize the audio server by calling its nAudioServer3::Open() function like the following code:

    audioServer->Open();

All neccessary works for audio server were done. The next section shows how to play sounds in a game loop.

Sound Playing

Sounds are played in a similiar way what the nodes are rendered. Call nAudioServer3::BeginScene() before playing sounds and then nAudioServer3::UpdateListener() to update the listener to set any changes of the position, orientation or velocity values. You can now play sounds. After playing sounds call nAudioServer::EndScene(). The following code shows how to play sounds in a game loop:

    audioServer->BeginScene(time);
    audioServer->UpdateListener(this->audioListener);
    ...
    // play sounds
    ...
    audioServer->EndScene();

Audio Server Shutdown

When the application is closing, the audio server should be shutdown by calling its Close() member function:

    audioServer->Close();


Classes
class	nAudioFile
	A generic base class for read access to audio files. Derive subclass for specific file formats/codecs. More...
class	nAudioServer3
class	nDSound3
	DirectSound based implementation of nSound3. Works together with nDSoundServer3 and nDSoundResource. More...
class	nDSoundResource
	An implementation of the nSoundResource class on top of DirectSound. More...
class	nDSoundServer3
	nAudioServer3 implemention using DirectSound. More...
class	nListener3
class	nOggFile
	Provide read-access to a ogg file. More...
class	nSound3
class	nSoundResource
class	nWavFile
	Provide read-access to a wav file. More...

Blogroll

Documentation

Links