Xors3d Engine
Audio

Functions

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

Function Documentation

Sound* xLoadSound ( const char *  path)

Loads a sound file into memory.

Parameters:
pathName of sound file. Formats supported: raw/wav/mp3/ogg
Sound* 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
void xFreeSound ( Sound *  sound)

Frees up a sound.

Parameters:
soundSound handle
void 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
void 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)
void 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)
void 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)
int xPlaySound ( Sound *  sound)

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

Parameters:
soundSound handle
void xStopChannel ( int  channel)

Stops channel playing.

Parameters:
channelChannel handle
void 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
void 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
int 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
void 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
void 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
void 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
int 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
int 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
Entity* 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
Entity* xGetListener ( )

Returns current listener handle.

int xInitalizeSound ( )

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