2 * This file is part of DisOrder.
3 * Copyright (C) 2009 Richard Kettlewell
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.
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.
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/>.
19 /** @file lib/uaudio.h
20 * @brief Uniform audio interface
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
;
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
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.
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.
47 typedef size_t uaudio_callback(void *buffer
,
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
56 * Used with uaudio_thread_start() etc.
58 typedef size_t uaudio_playcallback(void *buffer
, size_t samples
);
60 /** @brief Audio API definition */
62 /** @brief Name of this API */
65 /** @brief List of options, terminated by NULL */
66 const char *const *options
;
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
73 * This does resource-intensive setup for the output device.
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.
79 void (*start
)(uaudio_callback
*callback
,
83 * @param ua Handle returned by uaudio_open()
85 * This undoes the effect of @c start.
89 /** @brief Enable output
91 * A background thread will start calling @c callback as set by @c
92 * start and playing the audio data received from it.
94 void (*activate
)(void);
96 /** @brief Disable output
98 * The background thread will stop calling @c callback.
100 void (*deactivate
)(void);
102 /** @brief Open mixer device */
103 void (*open_mixer
)(void);
105 /** @brief Closer mixer device */
106 void (*close_mixer
)(void);
108 /** @brief Get volume
109 * @param left Where to put the left-channel value
110 * @param right Where to put the right-channel value
112 * 0 is silent and 100 is maximum volume.
114 void (*get_volume
)(int *left
, int *right
);
116 /** @brief Set volume
117 * @param left Pointer to left-channel value (updated)
118 * @param right Pointer to right-channel value (updated)
120 * The values are updated with those actually set by the underlying system
123 * 0 is silent and 100 is maximum volume.
125 void (*set_volume
)(int *left
, int *right
);
127 /** @brief Set configuration */
128 void (*configure
)(void);
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
,
137 uaudio_playcallback
*playcallback
,
140 void uaudio_thread_stop(void);
141 void uaudio_thread_activate(void);
142 void uaudio_thread_deactivate(void);
143 void uaudio_schedule_synchronize(void);
144 void uaudio_schedule_update(size_t written_samples
);
145 void uaudio_schedule_init(void);
146 const struct uaudio
*uaudio_find(const char *name
);
148 extern uint64_t uaudio_schedule_timestamp
;
149 extern int uaudio_schedule_reactivated
;
151 #if HAVE_COREAUDIO_AUDIOHARDWARE_H
152 extern const struct uaudio uaudio_coreaudio
;
155 #if HAVE_ALSA_ASOUNDLIB_H
156 extern const struct uaudio uaudio_alsa
;
159 #if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
160 extern const struct uaudio uaudio_oss
;
163 extern const struct uaudio uaudio_rtp
;
165 extern const struct uaudio uaudio_command
;
167 extern const struct uaudio
*const uaudio_apis
[];
169 #endif /* UAUDIO_H */