git.ozlabs.org Git - ccan/blob - ccan/wwviaudio/wwviaudio.h

   1 #ifndef _WWVIAUDIO_H_
   2 #define _WWVIAUDIO_H_
   3 /*
   4     (C) Copyright 2007,2008, Stephen M. Cameron.
   5
   6     This file is part of wordwarvi.
   7
   8     wordwarvi is free software; you can redistribute it and/or modify
   9     it under the terms of the GNU General Public License as published by
  10     the Free Software Foundation; either version 2 of the License, or
  11     (at your option) any later version.
  12
  13     wordwarvi is distributed in the hope that it will be useful,
  14     but WITHOUT ANY WARRANTY; without even the implied warranty of
  15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16     GNU General Public License for more details.
  17
  18     You should have received a copy of the GNU General Public License
  19     along with wordwarvi; if not, write to the Free Software
  20     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  21
  22  */
  23
  24 #ifdef WWVIAUDIO_DEFINE_GLOBALS
  25 #define GLOBAL
  26 #else
  27 #define GLOBAL extern
  28 #endif
  29
  30 #define WWVIAUDIO_MUSIC_SLOT (0)
  31 #define WWVIAUDIO_SAMPLE_RATE   (44100)
  32 #define WWVIAUDIO_ANY_SLOT (-1)
  33
  34 /*
  35  *             Configuration functions.
  36  */
  37 /* Disables the music channel.  Meant to be called prior to
  38  * wwviaudio_initialize_portaudio
  39  */
  40 GLOBAL void wwviaudio_set_nomusic(void);
  41
  42 /* Set the audio device number to the given value
  43  * This is meant to be called prior to calling
  44  * wwviaudio_initialize_portaudio.  If you don't use
  45  * this function, portaudio's default device will be
  46  * used.  This function provides a way to use a
  47  * device other than the default
  48  */
  49 GLOBAL int wwviaudio_set_sound_device(int device);
  50
  51 /* Initialize portaudio and start the audio engine.
  52  * Space will be allocated to allow for the specified
  53  * number of concurrently playing sounds.  The 2nd parameter
  54  * indicates how many different sound clips are to be held
  55  * in memory at once.  e.g. if your app has five different
  56  * sounds that it plays, then this would be 5.
  57  * 0 is returned on success, -1 otherwise.
  58  */
  59 GLOBAL int wwviaudio_initialize_portaudio(int maximum_concurrent_sounds,
  60         int maximum_sound_clips);
  61
  62 /* Stop portaudio and the audio engine. Space allocated
  63  * during initialization is freed.
  64  */
  65 GLOBAL void wwviaudio_stop_portaudio(void);
  66
  67 /*
  68  *             Audio data functions
  69  */
  70
  71 /* Read and decode an ogg vorbis audio file into a numbered buffer
  72  * The sound_number parameter is used later with wwviaudio_play_music and
  73  * wwviaudio_add_sound.  0 is returned on success, -1 otherwise.
  74  * Audio files should be 44100Hz, MONO.  The sound number is one you
  75  * provide which will then be associated with that sound.
  76  */
  77 GLOBAL int wwviaudio_read_ogg_clip(int sound_number, char *filename);
  78
  79 /*
  80  *             Global sound control functions.
  81  */
  82
  83 /* Suspend all audio playback.  Silence is output. */
  84 GLOBAL void wwviaudio_pause_audio(void);
  85
  86 /* Resume all previously playing audio from whence it was previusly paused. */
  87 GLOBAL void wwviaudio_resume_audio(void);
  88
  89 /*
  90  *             Music channel related functions
  91  */
  92
  93 /* Begin playing a numbered buffer into the mix on the music channel
  94  * The channel number of the music channel is returned.
  95  */
  96 GLOBAL int wwviaudio_play_music(int sound_number);
  97
  98 /* Output silence on the music channel (pointer still advances though.) */
  99 GLOBAL void wwviaudio_silence_music(void);
 100
 101 /* Unsilence the music channel */
 102 GLOBAL void wwviaudio_resume_music(void);
 103
 104 /* Silence or unsilence the music channe. */
 105 GLOBAL void wwviaudio_toggle_music(void);
 106
 107 /* Stop playing the playing buffer from the music channel */
 108 GLOBAL void wwviaudio_cancel_music(void);
 109
 110 /*
 111  *             Sound effect (not music) related functions
 112  */
 113
 114 /* Begin playing a sound on a non-music channel.  The channel is returned.
 115  * sound_number refers to a sound previously associated with the number by
 116  * wwviaudio_read_ogg_clip()
 117  */
 118 GLOBAL /* channel */ int wwviaudio_add_sound(int sound_number);
 119
 120 /* Begin playing a sound on a non-music channel.  The channel is returned.
 121  * If fewer than five channels are open, the sound is not played, and -1
 122  * is returned.
 123  */
 124 GLOBAL void wwviaudio_add_sound_low_priority(int sound_number);
 125
 126 /* Silence all channels but the music channel (pointers still advance though) */
 127 GLOBAL void wwviaudio_silence_sound_effects(void);
 128
 129 /* Unsilence all channels but the music channel */
 130 GLOBAL void wwviaudio_resume_sound_effects(void);
 131
 132 /* Either silence or unsilence all but the music channel */
 133 GLOBAL void wwviaudio_toggle_sound_effects(void);
 134
 135 /* Stop playing the playing buffer from the given channel */
 136 GLOBAL void wwviaudio_cancel_sound(int channel);
 137
 138
 139 /* Stop playing the playing buffer from all channels */
 140 GLOBAL void wwviaudio_cancel_all_sounds(void);
 141
 142 /*
 143         Example usage, something along these lines:
 144
 145         if (wwviaudio_initialize_portaudio() != 0)
 146                 bail_out_and_die();
 147
 148         You would probably use #defines or enums rather than bare ints...
 149         wwviaudio_read_ogg_clip(1, "mysound1.ogg");
 150         wwviaudio_read_ogg_clip(2, "mysound2.ogg");
 151         wwviaudio_read_ogg_clip(3, "mysound3.ogg");
 152         wwviaudio_read_ogg_clip(4, "mymusic.ogg");
 153
 154         ...
 155
 156         wwviaudio_play_music(4); <-- begins playing music in background, returns immediately
 157
 158         while (program isn't done) {
 159                 do_stuff();
 160                 if (something happened)
 161                         wwviaudio_add_sound(1);
 162                 if (something else happened)
 163                         wwviaudio_add_sound(2);
 164                 time_passes();
 165         }
 166
 167         wwviaudio_cancel_all_sounds();
 168         wwviaduio_stop_portaudio();
 169 */
 170 #undef GLOBAL
 171 #endif