4 (C) Copyright 2007,2008, Stephen M. Cameron.
6 This file is part of wordwarvi.
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.
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.
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
24 #ifdef WWVIAUDIO_DEFINE_GLOBALS
30 #define WWVIAUDIO_MUSIC_SLOT (0)
31 #define WWVIAUDIO_SAMPLE_RATE (44100)
32 #define WWVIAUDIO_ANY_SLOT (-1)
35 * Configuration functions.
37 /* Disables the music channel. Meant to be called prior to
38 * wwviaudio_initialize_portaudio
40 GLOBAL void wwviaudio_set_nomusic(void);
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
49 GLOBAL int wwviaudio_set_sound_device(int device);
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.
59 GLOBAL int wwviaudio_initialize_portaudio(int maximum_concurrent_sounds,
60 int maximum_sound_clips);
62 /* Stop portaudio and the audio engine. Space allocated
63 * during initialization is freed.
65 GLOBAL void wwviaudio_stop_portaudio(void);
68 * Audio data functions
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.
77 GLOBAL int wwviaudio_read_ogg_clip(int sound_number, char *filename);
80 * Global sound control functions.
83 /* Suspend all audio playback. Silence is output. */
84 GLOBAL void wwviaudio_pause_audio(void);
86 /* Resume all previously playing audio from whence it was previusly paused. */
87 GLOBAL void wwviaudio_resume_audio(void);
90 * Music channel related functions
93 /* Begin playing a numbered buffer into the mix on the music channel
94 * The channel number of the music channel is returned.
96 GLOBAL int wwviaudio_play_music(int sound_number);
98 /* Output silence on the music channel (pointer still advances though.) */
99 GLOBAL void wwviaudio_silence_music(void);
101 /* Unsilence the music channel */
102 GLOBAL void wwviaudio_resume_music(void);
104 /* Silence or unsilence the music channe. */
105 GLOBAL void wwviaudio_toggle_music(void);
107 /* Stop playing the playing buffer from the music channel */
108 GLOBAL void wwviaudio_cancel_music(void);
111 * Sound effect (not music) related functions
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()
118 GLOBAL /* channel */ int wwviaudio_add_sound(int sound_number);
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
124 GLOBAL void wwviaudio_add_sound_low_priority(int sound_number);
126 /* Silence all channels but the music channel (pointers still advance though) */
127 GLOBAL void wwviaudio_silence_sound_effects(void);
129 /* Unsilence all channels but the music channel */
130 GLOBAL void wwviaudio_resume_sound_effects(void);
132 /* Either silence or unsilence all but the music channel */
133 GLOBAL void wwviaudio_toggle_sound_effects(void);
135 /* Stop playing the playing buffer from the given channel */
136 GLOBAL void wwviaudio_cancel_sound(int channel);
139 /* Stop playing the playing buffer from all channels */
140 GLOBAL void wwviaudio_cancel_all_sounds(void);
143 Example usage, something along these lines:
145 if (wwviaudio_initialize_portaudio() != 0)
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");
156 wwviaudio_play_music(4); <-- begins playing music in background, returns immediately
158 while (program isn't done) {
160 if (something happened)
161 wwviaudio_add_sound(1);
162 if (something else happened)
163 wwviaudio_add_sound(2);
167 wwviaudio_cancel_all_sounds();
168 wwviaduio_stop_portaudio();