Overview
--------
Use these functions for playing wave, midi and mp3 files.
All wave files must:
- be 8 bit unsigned, not 16 bit
- have the same wave configuration (same mono/stereo and samplefrequence)
Midi files are converted in real time to wave via Timidity++ code and
use the actual wave configuration, which is
- the configuration of init_sound() if no wave file was loaded
- the configuration of the last loaded or just playing wave file
But there is also a possibility to convert midi files and save them as
wave file with vgag-config.sh, see general terms and compiling.
The same is for mp3 file; they are converted in real time to wave via
mpg123 code. They also can be converted to wave files with vgag-config.sh.
Therefore all wave files must have the same configuration and this
configuration should also be loaded with init_sound().
To be compatible with mp3 files use a samplefrequence of 11025 or 22050.
The sound server has 8 channels, there can be played up to 8 wave/midi/mp3
files simultaneously.
(Something else:
At the moment wave data is played with OSS or ALSA support.
If you want to create support for other wave devices,
see file vgag-wave.h for a short description and file wave_oss.h
for an example.)
The functions
-------------
for init_sound() please see Initializing and ending functions.
int load_wave(const char * arg1,int arg2):
load a wave/midi/mp3 file and connect it to a wave number.
Arguments:
- arg1: path and filename of the wave/midi/mp3 file
(you should use a full path, otherwise you had to know the current
directory of the sound server, which is the same you had when
you called "init_sound()")
- arg2: emulation mode:
TYP_IS_WAVE for wave files
TYP_IS_MIDI for midi files
TYP_IS_MP3 for mp3 files
TYP_IS_EXTENSION to recognize the type from file extension:
".wav[e]" or ".mid[i]" or ".mp3"
Return value: wave number for this sound file
or 0=error (sound server exit)
Example:
int wn[3];
if ((wn[0]=load_wave("/path/wave1.wav",TYP_IS_WAVE))==0) { [...error...] }
if ((wn[1]=load_wave("/path/wave2.wav",TYP_IS_WAVE))==0) { [...error...] }
if ((wn[2]=load_wave("/path/midi1.mid",TYP_IS_MIDI))==0) { [...error...] }
void play_wave(int arg1,int arg2,short arg3,short arg4):
play a wave/midi/mp3 file assigned to a wave number with load_wave().
Arguments:
- arg1: wave number got from load_wave()
- arg2: channel numbers bit or'ed
from CN_(1) to CN_(8)
or CN_ALL for all channels
The sound server chooses from the given channels a free one
to play the sound; if there is no free one, one of these
is killed and used for.
- arg3: 0=play once to the end
>0=loop playing with a pause of arg3 seconds
- arg4: 0=start with volume=100%
>0=time in seconds to increase volume up to 100%
Note: If you use an increasing volume (arg4>0) there is a difference
whether the channel was playing before or unused.
If it was unused, the channel volume needs arg4 seconds to
increase from 0% to 100%.
If it was playing, the channel volume needs arg4 seconds first
to decrease the former sound from 100% to 0%, then arg4 seconds
again to increase the new sound from 0% to 100%.
Normally you define certain channels for certain sound categories,
e.g. channel 1 and 2 for background music, channel 3 to 5 for
voices, channel 6 to 8 for sound effects.
Example:
int wn;
if ((wn=load_wave("/path/wave1.wav",TYP_IS_WAVE))==0) { [...error...] }
// play sound at channel 1 or 2 or 3 once with full volume
play_wave(wn,CN_(1)|CN_(2)|CN_(3),0,0);
// play sound at any channel looping with 3 seconds pause and full volume
play_wave(wn,CN_ALL,3,0);
// play sound at channel 1 once with 5 seconds increasing volume
play_wave(wn,CN_(1),0,5);
void stop_wave(int arg1,short arg2):
stop playing wave/midi/mp3 at certain channels.
Arguments:
- arg1: channel numbers bit or'ed
from CN_(1) to CN_(8)
or CN_ALL for all channels
All selected channels are stopped playing.
- arg2: 0=stop playing at once
>0=time in seconds to decrease volume down to 0%
Example:
// stop channel 5 and 7 at once
stop_wave(CN_(5)|CN_(7),0);
// stop all channels with 5 seconds decreasing volume
stop_wave(CN_ALL,5);
void pause_wave(int arg1):
pause playing wave/midi/mp3 at certain channels.
Arguments:
- arg1: channel numbers bit or'ed
from CN_(1) to CN_(8)
or CN_ALL for all channels
All selected channels are paused playing.
Example:
// pause channel 5 and 7
pause_wave(CN_(5)|CN_(7));
// pause all channels
pause_wave(CN_ALL);
void continue_wave(int arg1):
continue playing wave/midi/mp3 at certain channels after pausing them.
Arguments:
- arg1: channel numbers bit or'ed
from CN_(1) to CN_(8)
or CN_ALL for all channels
All selected channels are continued playing.
Example:
// continue channel 5 and 7
continue_wave(CN_(5)|CN_(7));
// continue all channels
continue_wave(CN_ALL);
void volume_wave(int arg1,short arg2):
change volume percent at certain channels, that is, make certain
channel playing more or less loud.
Arguments:
- arg1: channel numbers bit or'ed
from CN_(1) to CN_(8)
or CN_ALL for all channels
All selected channels are changed.
- arg2: 0 to 30
where 0 = 0% volume
1 = 10% volume
2 = 20% volume
...
10 = 100% volume
...
30 = 300% volume
Example:
// change volume at channels 1 and 4 to 110%
volume_wave(CN_(1)|CN_(4),11);
void accel_wave(short arg1,short arg2):
accelerate calculating for playing wave/midi/mp3 at cost of quality.
Arguments:
- arg1: 0=do not change actual samplefrequence factor
1 to 4 = divide original samplefrequence with arg1
- arg2: 0=do not change actual mono/stereo settings
1=set all to mono
2=set mono files to mono and stereo files to stereo
Note: Wave files at high quality need more calculating power, especially
when also playing midi or mp3 files, which are converted in real time
to wave. If this causes the game to be too slow, use this function
to set the quality of your sound files down.
There are two ways:
- set down the samplefrequence
e.g. original 44100 with arg1=2 results in 22050
original 44100 with arg1=4 results in 11025
- set all to mono
This affects wave, midi and mp3 and all channels.
When using this function all sounds are stopped. You have to
start them again. Therefore it is better to use this function
outside your game loop, e.g. in a configuration menu.
Example:
accel_wave(0,0); // don't change anything - useless
accel_wave(1,0); // set original samplefrequence
accel_wave(2,0); // set half of original samplefrequence
accel_wave(0,1); // convert all sound to mono
accel_wave(0,2); // set all sound back to original mono/stereo
accel_wave(4,1); // set a quarter of original samplefrequence
// and convert all sound to mono
int set_vol(int arg1,int arg2):
set main or pcm volume for all channels.
Arguments:
- arg1: 0 to 100 = volume number
-1=don't set volume but get only current volume number
- arg2: 0=set main volume
1=set pcm volume
Return value: 0 to 100 = current volume number if arg1=-1
or volume number before change if arg1>=0
-1=error
Example:
int vol;
// get current volume of main volume, do no change it
vol=set_vol(-1,0);
// get current volume of main volume and change it to 40
vol=set_vol(40,0);
for end_sound() please see Initializing and ending functions.
Home | Previous: Key and mouse functions | Next: Network functions