chiark / gitweb /
Merge from disorder.dev.
[disorder] / lib / uaudio.h
1 /*
2  * This file is part of DisOrder.
3  * Copyright (C) 2009 Richard Kettlewell
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation, either version 3 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  * 
15  * You should have received a copy of the GNU General Public License
16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
17  */
18
19 /** @file lib/uaudio.h
20  * @brief Uniform audio interface
21  */
22
23 #ifndef UAUDIO_H
24 #define UAUDIO_H
25
26 extern int uaudio_rate;
27 extern int uaudio_bits;
28 extern int uaudio_channels;
29 extern int uaudio_signed;
30 extern size_t uaudio_sample_size;
31
32 /** @brief Callback to get audio data
33  * @param buffer Where to put audio data
34  * @param max_samples How many samples to supply
35  * @param userdata As passed to uaudio_open()
36  * @return Number of samples filled
37  *
38  * This function should not block if possible (better to fill the buffer with
39  * 0s) and should definitely not block indefinitely.  This great caution with
40  * any locks or syscalls!  In particular avoid it taking a lock that may be
41  * held while any of the @ref uaudio members are called.
42  *
43  * If it's more convenient, it's OK to return less than the maximum number of
44  * samples (including 0) provided you expect to be called again for more
45  * samples immediately.
46  */
47 typedef size_t uaudio_callback(void *buffer,
48                                size_t max_samples,
49                                void *userdata);
50
51 /** @brief Callback to play audio data
52  * @param buffer Pointer to audio buffer
53  * @param samples Number of samples to play
54  * @param flags Flags word
55  * @return Number of samples played
56  *
57  * Used with uaudio_thread_start() etc.
58  *
59  * @p flags is a bitmap giving the current pause state and transitions:
60  * - @ref UAUDIO_PAUSE if this is the first call of a pause
61  * - @ref UAUDIO_RESUME if this is the first call of a resumse
62  * - @ref UAUDIO_PLAYING if this is outside a pause
63  * - @ref UAUDIO_PAUSED if this is in a pause
64  *
65  * During a pause, the sample data is guaranteed to be 0.
66  */
67 typedef size_t uaudio_playcallback(void *buffer, size_t samples,
68                                    unsigned flags);
69
70 /** @brief Start of a pause */
71 #define UAUDIO_PAUSE 0x0001
72
73 /** @brief End of a pause */
74 #define UAUDIO_RESUME 0x0002
75
76 /** @brief Currently playing */
77 #define UAUDIO_PLAYING 0x0004
78
79 /** @brief Currently paused */
80 #define UAUDIO_PAUSED 0x0008
81
82 /** @brief Audio API definition */
83 struct uaudio {
84   /** @brief Name of this API */
85   const char *name;
86
87   /** @brief List of options, terminated by NULL */
88   const char *const *options;
89
90   /** @brief Do slow setup
91    * @param ua Handle returned by uaudio_open()
92    * @param callback Called for audio data
93    * @param userdata Passed to @p callback
94    *
95    * This does resource-intensive setup for the output device.
96    *
97    * For instance it might open mixable audio devices or network sockets.  It
98    * will create any background thread required.  However, it must not exclude
99    * other processes from outputting sound.
100    */
101   void (*start)(uaudio_callback *callback,
102                 void *userdata);
103
104   /** @brief Tear down
105    * @param ua Handle returned by uaudio_open()
106    *
107    * This undoes the effect of @c start.
108    */
109   void (*stop)(void);
110
111   /** @brief Enable output
112    *
113    * A background thread will start calling @c callback as set by @c
114    * start and playing the audio data received from it.
115    */
116   void (*activate)(void);
117
118   /** @brief Disable output
119    *
120    * The background thread will stop calling @c callback.
121    */
122   void (*deactivate)(void);
123
124   /** @brief Open mixer device */
125   void (*open_mixer)(void);
126
127   /** @brief Closer mixer device */
128   void (*close_mixer)(void);
129
130   /** @brief Get volume
131    * @param left Where to put the left-channel value
132    * @param right Where to put the right-channel value
133    *
134    * 0 is silent and 100 is maximum volume.
135    */
136   void (*get_volume)(int *left, int *right);
137
138   /** @brief Set volume
139    * @param left Pointer to left-channel value (updated)
140    * @param right Pointer to right-channel value (updated)
141    *
142    * The values are updated with those actually set by the underlying system
143    * call.
144    *
145    * 0 is silent and 100 is maximum volume.
146    */
147   void (*set_volume)(int *left, int *right);
148
149   /** @brief Set configuration */
150   void (*configure)(void);
151   
152 };
153
154 void uaudio_set_format(int rate, int channels, int samplesize, int signed_);
155 void uaudio_set(const char *name, const char *value);
156 char *uaudio_get(const char *name, const char *default_value);
157 void uaudio_thread_start(uaudio_callback *callback,
158                          void *userdata,
159                          uaudio_playcallback *playcallback,
160                          size_t min,
161                          size_t max,
162                          unsigned flags);
163
164 void uaudio_thread_stop(void);
165 void uaudio_thread_activate(void);
166 void uaudio_thread_deactivate(void);
167 uint32_t uaudio_schedule_sync(void);
168 void uaudio_schedule_sent(size_t nsamples_sent);
169 void uaudio_schedule_init(void);
170 const struct uaudio *uaudio_find(const char *name);
171
172 extern uint64_t uaudio_schedule_timestamp;
173 extern int uaudio_schedule_reactivated;
174
175 #if HAVE_COREAUDIO_AUDIOHARDWARE_H
176 extern const struct uaudio uaudio_coreaudio;
177 #endif
178
179 #if HAVE_ALSA_ASOUNDLIB_H
180 extern const struct uaudio uaudio_alsa;
181 #endif
182
183 #if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
184 extern const struct uaudio uaudio_oss;
185 #endif
186
187 extern const struct uaudio uaudio_rtp;
188
189 extern const struct uaudio uaudio_command;
190
191 extern const struct uaudio *const uaudio_apis[];
192
193 #endif /* UAUDIO_H */
194
195 /*
196 Local Variables:
197 c-basic-offset:2
198 comment-column:40
199 fill-column:79
200 indent-tabs-mode:nil
201 End:
202 */