New junkcode.
[ccan] / 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