chiark / gitweb /
The command backend now sends 0s rather than suspending output when a
[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  * @return Number of samples played
55  *
56  * Used with uaudio_thread_start() etc.
57  */
58 typedef size_t uaudio_playcallback(void *buffer, size_t samples);
59
60 /** @brief Audio API definition */
61 struct uaudio {
62   /** @brief Name of this API */
63   const char *name;
64
65   /** @brief List of options, terminated by NULL */
66   const char *const *options;
67
68   /** @brief Do slow setup
69    * @param ua Handle returned by uaudio_open()
70    * @param callback Called for audio data
71    * @param userdata Passed to @p callback
72    *
73    * This does resource-intensive setup for the output device.
74    *
75    * For instance it might open mixable audio devices or network sockets.  It
76    * will create any background thread required.  However, it must not exclude
77    * other processes from outputting sound.
78    */
79   void (*start)(uaudio_callback *callback,
80                 void *userdata);
81
82   /** @brief Tear down
83    * @param ua Handle returned by uaudio_open()
84    *
85    * This undoes the effect of @c start.
86    */
87   void (*stop)(void);
88
89   /** @brief Enable output
90    *
91    * A background thread will start calling @c callback as set by @c
92    * start and playing the audio data received from it.
93    */
94   void (*activate)(void);
95
96   /** @brief Disable output
97    *
98    * The background thread will stop calling @c callback.
99    */
100   void (*deactivate)(void);
101
102   /** @brief Open mixer device */
103   void (*open_mixer)(void);
104
105   /** @brief Closer mixer device */
106   void (*close_mixer)(void);
107
108   /** @brief Get volume
109    * @param left Where to put the left-channel value
110    * @param right Where to put the right-channel value
111    *
112    * 0 is silent and 100 is maximum volume.
113    */
114   void (*get_volume)(int *left, int *right);
115
116   /** @brief Set volume
117    * @param left Pointer to left-channel value (updated)
118    * @param right Pointer to right-channel value (updated)
119    *
120    * The values are updated with those actually set by the underlying system
121    * call.
122    *
123    * 0 is silent and 100 is maximum volume.
124    */
125   void (*set_volume)(int *left, int *right);
126
127   /** @brief Set configuration */
128   void (*configure)(void);
129   
130 };
131
132 void uaudio_set_format(int rate, int channels, int samplesize, int signed_);
133 void uaudio_set(const char *name, const char *value);
134 char *uaudio_get(const char *name, const char *default_value);
135 void uaudio_thread_start(uaudio_callback *callback,
136                          void *userdata,
137                          uaudio_playcallback *playcallback,
138                          size_t min,
139                          size_t max,
140                          unsigned flags);
141
142 /** @brief Fake pauses
143  *
144  * This flag is used for audio backends that cannot sensibly be paused.
145  * The thread support code will supply silence while deactivated in this
146  * case.
147  */
148 #define UAUDIO_THREAD_FAKE_PAUSE 0x00000001
149
150 void uaudio_thread_stop(void);
151 void uaudio_thread_activate(void);
152 void uaudio_thread_deactivate(void);
153 void uaudio_schedule_synchronize(void);
154 void uaudio_schedule_update(size_t written_samples);
155 void uaudio_schedule_init(void);
156 const struct uaudio *uaudio_find(const char *name);
157
158 extern uint64_t uaudio_schedule_timestamp;
159 extern int uaudio_schedule_reactivated;
160
161 #if HAVE_COREAUDIO_AUDIOHARDWARE_H
162 extern const struct uaudio uaudio_coreaudio;
163 #endif
164
165 #if HAVE_ALSA_ASOUNDLIB_H
166 extern const struct uaudio uaudio_alsa;
167 #endif
168
169 #if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
170 extern const struct uaudio uaudio_oss;
171 #endif
172
173 extern const struct uaudio uaudio_rtp;
174
175 extern const struct uaudio uaudio_command;
176
177 extern const struct uaudio *const uaudio_apis[];
178
179 #endif /* UAUDIO_H */
180
181 /*
182 Local Variables:
183 c-basic-offset:2
184 comment-column:40
185 fill-column:79
186 indent-tabs-mode:nil
187 End:
188 */