chiark - git - mdw - disorder/blob - 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 */