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