chiark / gitweb /
Fix mis-merged trackdb_open().
[disorder] / lib / uaudio.h
CommitLineData
7a2c7068
RK
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
4fd38868
RK
26extern int uaudio_rate;
27extern int uaudio_bits;
28extern int uaudio_channels;
29extern int uaudio_signed;
30extern size_t uaudio_sample_size;
31
7a2c7068
RK
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
d4170ca7
RK
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.
7a2c7068 46 */
4fd38868 47typedef size_t uaudio_callback(void *buffer,
7a2c7068
RK
48 size_t max_samples,
49 void *userdata);
50
4fd38868
RK
51/** @brief Callback to play audio data
52 * @param buffer Pointer to audio buffer
53 * @param samples Number of samples to play
b1f6ca8c 54 * @param flags Flags word
4fd38868
RK
55 * @return Number of samples played
56 *
57 * Used with uaudio_thread_start() etc.
b1f6ca8c
RK
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.
4fd38868 66 */
b1f6ca8c
RK
67typedef 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
4fd38868 81
7a2c7068
RK
82/** @brief Audio API definition */
83struct 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
b50cfb8a
RK
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);
ba70caca
RK
148
149 /** @brief Set configuration */
150 void (*configure)(void);
b50cfb8a 151
7a2c7068 152};
4fd38868
RK
153
154void uaudio_set_format(int rate, int channels, int samplesize, int signed_);
7a2c7068 155void uaudio_set(const char *name, const char *value);
b50cfb8a 156char *uaudio_get(const char *name, const char *default_value);
4fd38868
RK
157void uaudio_thread_start(uaudio_callback *callback,
158 void *userdata,
159 uaudio_playcallback *playcallback,
160 size_t min,
63761c19
RK
161 size_t max,
162 unsigned flags);
163
4fd38868
RK
164void uaudio_thread_stop(void);
165void uaudio_thread_activate(void);
166void uaudio_thread_deactivate(void);
b1f6ca8c 167uint32_t uaudio_schedule_sync(void);
1c140a81 168void uaudio_schedule_sent(size_t nsamples_sent);
ec57f6c9 169void uaudio_schedule_init(void);
b50cfb8a 170const struct uaudio *uaudio_find(const char *name);
ec57f6c9
RK
171
172extern uint64_t uaudio_schedule_timestamp;
173extern int uaudio_schedule_reactivated;
7a2c7068
RK
174
175#if HAVE_COREAUDIO_AUDIOHARDWARE_H
176extern const struct uaudio uaudio_coreaudio;
177#endif
178
179#if HAVE_ALSA_ASOUNDLIB_H
180extern const struct uaudio uaudio_alsa;
181#endif
182
183#if HAVE_SYS_SOUNDCARD_H || EMPEG_HOST
184extern const struct uaudio uaudio_oss;
185#endif
186
187extern const struct uaudio uaudio_rtp;
188
66288757 189extern const struct uaudio uaudio_command;
7a2c7068 190
5b053666 191extern const struct uaudio *const uaudio_apis[];
efd23a80 192
7a2c7068
RK
193#endif /* UAUDIO_H */
194
195/*
196Local Variables:
197c-basic-offset:2
198comment-column:40
199fill-column:79
200indent-tabs-mode:nil
201End:
202*/