![]() |
Xors3d Engine
|
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. |
BBDECL Sound* BBCALL xLoadSound | ( | const char * | path | ) |
Loads a sound file into memory.
path | Name 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()
path | Filename of sound file to be loaded and used as 3D sound |
BBDECL void BBCALL xFreeSound | ( | Sound * | sound | ) |
Frees up a sound.
sound | Sound 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
sound | Sound 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.
sound | Sound handle |
pitch | Valid 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
sound | Sound handle |
volume | Floating 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.
sound | Sound handle |
pan | Floating 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.
sound | Sound handle |
BBDECL void BBCALL xStopChannel | ( | int | channel | ) |
Stops channel playing.
channel | Channel 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.
channel | Channel 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()).
channel | Channel 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
path | Name 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.
channel | Channel handle |
pitch | Pitch 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).
channel | Channel handle |
volume | Volume 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.
channel | Channel handle |
pan | Panning 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.
channel | Channel 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
sound | Sound handle |
entity | Entity 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.
parent | Parent entity handle |
roFactor | The rate at which volume diminishes with distance |
doplerFactor | The severity of the doppler effect |
distFactor | Artificially 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)