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