Vgagames: Sound functions:
==========================

 

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