Xors3d Engine
Audio

Functions

BBDECL void BBCALL xChannelPan (int channel, float pan)
 Sets channel panoram value.
BBDECL void BBCALL xChannelPitch (int channel, int pitch)
 Sets channel frequency.
BBDECL int BBCALL xChannelPlaying (int channel)
 Returns true if specified channel is being played.
BBDECL void BBCALL xChannelVolume (int channel, float volume)
 Sets channel volume.
BBDECL Entity *BBCALL xCreateListener (Entity *parent=NULL, float roFactor=1.0f, float doplerFactor=1.0f, float distFactor=1.0f)
 Creates a listener entity and returns its handle.
BBDECL int BBCALL xEmitSound (Sound *sound, Entity *entity)
 Emits a sound attached to the specified entity and returns a sound channel.
BBDECL void BBCALL xFreeSound (Sound *sound)
 Frees up a sound.
BBDECL Entity *BBCALL xGetListener ()
 Returns current listener handle.
BBDECL int BBCALL xInitalizeSound ()
 Initializes engine's sound system. Call it if you need to load sounds before setting graphics mode (xGraphics3D() will initialize sound itself)
BBDECL Sound *BBCALL xLoad3DSound (const char *path)
 Loads a sound and returns its handle for use with xEmitSound()
BBDECL Sound *BBCALL xLoadSound (const char *path)
 Loads a sound file into memory.
BBDECL void BBCALL xLoopSound (Sound *sound)
 Sets up play back a sound file in an endless loop (like for background music)
BBDECL void BBCALL xPauseChannel (int channel)
 Pauses channel playing.
BBDECL int BBCALL xPlayMusic (const char *path)
 This command will load and play a music file.
BBDECL int BBCALL xPlaySound (Sound *sound)
 Plays a sound previously loaded using the xLoadSound() command.
BBDECL void BBCALL xResumeChannel (int channel)
 Continues the playing of a sound sample or music track on the given channel after you have temporarily halted playback on that channel (via xPauseChannel()).
BBDECL void BBCALL xSoundPan (Sound *sound, float pan)
 Pans sound effect between the left and right speakers.
BBDECL void BBCALL xSoundPitch (Sound *sound, int pitch)
 Alters the pitch of a sound.
BBDECL void BBCALL xSoundVolume (Sound *sound, float volume)
 Alters the playback volume of sound effect.
BBDECL void BBCALL xStopChannel (int channel)
 Stops channel playing.

Function Documentation

BBDECL Sound* BBCALL xLoadSound ( const char *  path)

Loads a sound file into memory.

Parameters:
pathName of sound file. Formats supported: raw/wav/mp3/ogg
BBDECL Sound* BBCALL xLoad3DSound ( const char *  path)

Loads a sound and returns its handle for use with xEmitSound()

Parameters:
pathFilename of sound file to be loaded and used as 3D sound
BBDECL void BBCALL xFreeSound ( Sound *  sound)

Frees up a sound.

Parameters:
soundSound handle
BBDECL void BBCALL xLoopSound ( Sound *  sound)

Sets up play back a sound file in an endless loop (like for background music)

This command doesn't actually play the sound loop, just sets it up for looping. You still need to execute the xPlaySound() command to hear the sound

Parameters:
soundSound handle
BBDECL void BBCALL xSoundPitch ( Sound *  sound,
int  pitch 
)

Alters the pitch of a sound.

By changing the pitch, you can often reuse sounds for different uses or to simulate a 'counting up/down' sound. To make the sound 'higher pitched', increase the hertz. Conversely, decreasing the hertz will 'lower' the pitch. Note: this is in relation to the original hertz frequency of the sound.

Parameters:
soundSound handle
pitchValid playback hertz speed (up to 44000 hertz)
BBDECL void BBCALL xSoundVolume ( Sound *  sound,
float  volume 
)

Alters the playback volume of sound effect.

This command uses a floating point number from 0.0 to 1.0 to control the volume level

Parameters:
soundSound handle
volumeFloating point number from 0.0 (silence) to 1.0 (full volume)
BBDECL void BBCALL xSoundPan ( Sound *  sound,
float  pan 
)

Pans sound effect between the left and right speakers.

Parameters:
soundSound handle
panFloating point number from -1.0 (left) to 0.0 (center) to 1.0 (right)
BBDECL int BBCALL xPlaySound ( Sound *  sound)

Plays a sound previously loaded using the xLoadSound() command.

Parameters:
soundSound handle
BBDECL void BBCALL xStopChannel ( int  channel)

Stops channel playing.

Parameters:
channelChannel handle
BBDECL void BBCALL xPauseChannel ( int  channel)

Pauses channel playing.

When you are playing a sound channel, there may come a time you wish to pause the sound for whatever reason (like to play another sound effect). This command does this - and the channel can be resumed with the xResumeChannel() command. You can use xStopChannel() to actually halt the sound.

Parameters:
channelChannel handle
BBDECL void BBCALL xResumeChannel ( int  channel)

Continues the playing of a sound sample or music track on the given channel after you have temporarily halted playback on that channel (via xPauseChannel()).

Parameters:
channelChannel handle
BBDECL int BBCALL xPlayMusic ( const char *  path)

This command will load and play a music file.

You can't 'preload' the audio like you can a sound sample via the xLoadSound() command. Every time you call the xPlayMusic() command, the file is reloaded and played. This means that if you use the command while some graphics are moving on-screen, you may get a slight pause when the hard drive seeks and grabs the music file. To avoid this, you might want to use the xPlaySound()/xLoopSound() commands instead

Parameters:
pathName of music file
BBDECL void BBCALL xChannelPitch ( int  channel,
int  pitch 
)

Sets channel frequency.

You can alter the pitch of a sound channel that is playing (or in use and just paused). Use the frequency of your sound as the 'baseline' for pitch change. So if your sample is at 11025 hertz, increase the pitch to 22050 to make the pitch twice as high, 8000 to make it lower, etc. While similar to xSoundPitch(), this command let's you change the pitch individually of each and every channel in use.

Parameters:
channelChannel handle
pitchPitch to apply to the channel
BBDECL void BBCALL xChannelVolume ( int  channel,
float  volume 
)

Sets channel volume.

While xSoundVolume() happily changes the volume of the entire program, this command will let you adjust volume rates on a 'per channel' basis. Extremely useful. The volume value is a floating point value between 0.0 and 1.0 (0.0f = silence, 0.5 = half volume, 1.0 = full volume).

Parameters:
channelChannel handle
volumeVolume level floating value between 0.0 and 1.0
BBDECL void BBCALL xChannelPan ( int  channel,
float  pan 
)

Sets channel panoram value.

When you want to do real sound panning effects, this is the command you'll use. This will allow you to pan the sound channels on a 'per channel' basis between the left and right speakers. This command makes it very easy to produce some really killer stereophonic effects. The pan value is between -1 and 1 with 0 being perfect center. -1 is full left, and 1 is full right. To make it somewhere in between, try -0.5 for 50% left or 0.75 for 75% right.

Parameters:
channelChannel handle
panPanning value to denote channel playback
BBDECL int BBCALL xChannelPlaying ( int  channel)

Returns true if specified channel is being played.

Often you will need to know if a sound channel has completed playing or not. This command will return 1 if the sound is still playing or 0 if it has stopped. Use this to restart your background music or some other sound that might have stopped unintentionally.

Parameters:
channelChannel handle
BBDECL int BBCALL xEmitSound ( Sound *  sound,
Entity *  entity 
)

Emits a sound attached to the specified entity and returns a sound channel.

The sound must have been loaded using xLoad3DSound() for 3D effects

Parameters:
soundSound handle
entityEntity handle
BBDECL Entity* BBCALL xCreateListener ( Entity *  parent = NULL,
float  roFactor = 1.0f,
float  doplerFactor = 1.0f,
float  distFactor = 1.0f 
)

Creates a listener entity and returns its handle.

Currently, only a single listener is supported.

Parameters:
parentParent entity handle
roFactorThe rate at which volume diminishes with distance
doplerFactorThe severity of the doppler effect
distFactorArtificially scales distances
BBDECL Entity* BBCALL xGetListener ( )

Returns current listener handle.

BBDECL int BBCALL xInitalizeSound ( )

Initializes engine's sound system. Call it if you need to load sounds before setting graphics mode (xGraphics3D() will initialize sound itself)