1 /* 2 * Copyright (C) 2000-2019 the xine project 3 * 4 * This file is part of xine, a free video player. 5 * 6 * xine is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * xine is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA 19 */ 20 #ifndef HAVE_AUDIO_OUT_H 21 #define HAVE_AUDIO_OUT_H 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #include <xine/attributes.h> 28 #include <xine/os_types.h> 29 #include <xine/xineutils.h> 30 #include <xine/buffer.h> 31 32 struct plugin_node_s; 33 34 #define AUDIO_OUT_IFACE_VERSION 9 35 36 /* 37 * ao_driver_s contains the driver every audio output 38 * driver plugin has to implement. 39 */ 40 41 typedef struct ao_driver_s ao_driver_t; 42 43 struct ao_driver_s { 44 45 /* 46 * 47 * find out what output modes + capatilities are supported by 48 * this plugin (constants for the bit vector to return see above) 49 * 50 * See AO_CAP_* bellow. 51 */ 52 uint32_t (*get_capabilities) (ao_driver_t *); 53 54 /* 55 * open the driver and make it ready to receive audio data 56 * buffers may be flushed(!) 57 * 58 * return value: 0 : failure, >0 : output sample rate 59 */ 60 int (*open)(ao_driver_t *, uint32_t bits, uint32_t rate, int mode); 61 62 /* return the number of audio channels 63 */ 64 int (*num_channels)(ao_driver_t *self_gen); 65 66 /* return the number of bytes per frame. 67 * A frame is equivalent to one sample being output on every audio channel. 68 */ 69 int (*bytes_per_frame)(ao_driver_t *self_gen); 70 71 /* return the delay is frames measured by 72 * looking at pending samples in the audio output device 73 */ 74 int (*delay)(ao_driver_t *self_gen); 75 76 /* 77 * return gap tolerance (in pts) needed for this driver 78 */ 79 int (*get_gap_tolerance) (ao_driver_t *self_gen); 80 81 /* 82 * write audio data to audio output device 83 * return value: 84 * >0 => audio samples were processed ok 85 * 0 => audio samples were not yet processed, 86 * call write_audio_data with the _same_ samples again 87 */ 88 int (*write)(ao_driver_t *, 89 int16_t* audio_data, uint32_t num_samples); 90 91 /* 92 * this is called when the decoder no longer uses the audio 93 * output driver - the driver should get ready to get opened() again 94 */ 95 void (*close)(ao_driver_t *); 96 97 /* 98 * shut down this audio output driver plugin and 99 * free all resources allocated 100 */ 101 void (*exit) (ao_driver_t *); 102 103 /* 104 * Get, Set a property of audio driver. 105 * 106 * get_property() return 1 in success, 0 on failure. 107 * set_property() return value on success, ~value on failure. 108 * 109 * See AO_PROP_* below for available properties. 110 */ 111 int (*get_property) (ao_driver_t *, int property); 112 113 int (*set_property) (ao_driver_t *, int property, int value); 114 115 116 /* 117 * misc control operations on the audio device. 118 * 119 * See AO_CTRL_* below. 120 */ 121 int (*control) (ao_driver_t *, int cmd, /* arg */ ...); 122 123 /** 124 * @brief Pointer to the loaded plugin node. 125 * 126 * Used by the plugins loader. It's an opaque type when using the 127 * structure outside of xine's build. 128 */ 129 struct plugin_node_s *node XINE_PRIVATE_FIELD; 130 }; 131 132 typedef struct ao_format_s ao_format_t; 133 134 struct ao_format_s { 135 uint32_t bits; 136 uint32_t rate; 137 int mode; 138 }; 139 140 typedef struct audio_fifo_s audio_fifo_t; 141 142 typedef struct audio_buffer_s audio_buffer_t; 143 144 struct audio_buffer_s { 145 146 audio_buffer_t *next; 147 148 int16_t *mem; 149 int mem_size; 150 int num_frames; 151 152 int64_t vpts; 153 uint32_t frame_header_count; 154 uint32_t first_access_unit; 155 156 /* extra info coming from input or demuxers */ 157 extra_info_t *extra_info; 158 159 xine_stream_t *stream; /* stream that send that buffer */ 160 161 ao_format_t format; /* let each buffer carry it's own format info */ 162 }; 163 164 /* 165 * xine_audio_port_s contains the port every audio decoder talks to 166 * 167 * Remember that adding new functions to this structure requires 168 * adaption of the post plugin decoration layer. Be sure to look into 169 * src/xine-engine/post.[ch]. 170 */ 171 172 struct xine_audio_port_s { 173 uint32_t (*get_capabilities) (xine_audio_port_t *); /* for constants see below */ 174 175 /* * Get/Set audio property 176 * 177 * See AO_PROP_* bellow 178 */ 179 int (*get_property) (xine_audio_port_t *, int property); 180 int (*set_property) (xine_audio_port_t *, int property, int value); 181 182 /* open audio driver for audio output 183 * return value: 0:failure, >0:output sample rate 184 */ 185 /* when you are not a full-blown stream, but still need to open the port 186 * (e.g. you are a post plugin) it is legal to pass an anonymous stream */ 187 int (*open) (xine_audio_port_t *, xine_stream_t *stream, 188 uint32_t bits, uint32_t rate, int mode); 189 190 /* 191 * get a piece of memory for audio data 192 */ 193 audio_buffer_t * (*get_buffer) (xine_audio_port_t *); 194 195 /* 196 * append a buffer filled with audio data to the audio fifo 197 * for output 198 */ 199 /* when the frame does not originate from a stream, it is legal to pass an anonymous stream */ 200 void (*put_buffer) (xine_audio_port_t *, audio_buffer_t *buf, xine_stream_t *stream); 201 202 /* audio driver is no longer used by decoder => close */ 203 /* when you are not a full-blown stream, but still need to close the port 204 * (e.g. you are a post plugin) it is legal to pass an anonymous stream */ 205 void (*close) (xine_audio_port_t *self, xine_stream_t *stream); 206 207 /* called on xine exit */ 208 void (*exit) (xine_audio_port_t *); 209 210 /* 211 * misc control operations on the audio device. 212 * 213 * See AO_CTRL_* below. 214 */ 215 int (*control) (xine_audio_port_t *, int cmd, /* arg */ ...); 216 217 /* 218 * Flush audio_out fifo. 219 */ 220 void (*flush) (xine_audio_port_t *); 221 222 /* 223 * Check if port is opened for this stream and get parameters. 224 * The stream can be anonymous. 225 */ 226 int (*status) (xine_audio_port_t *, xine_stream_t *stream, 227 uint32_t *bits, uint32_t *rate, int *mode); 228 229 }; 230 231 typedef struct audio_driver_class_s audio_driver_class_t; 232 233 struct audio_driver_class_s { 234 235 /* 236 * open a new instance of this plugin class 237 */ 238 ao_driver_t* (*open_plugin) (audio_driver_class_t *, const void *data); 239 240 /** 241 * @brief short human readable identifier for this plugin class 242 */ 243 const char *identifier; 244 245 /** 246 * @brief human readable (verbose = 1 line) description for this plugin class 247 * 248 * The description is passed to gettext() to internationalise. 249 */ 250 const char *description; 251 252 /** 253 * @brief Optional non-standard catalog to use with dgettext() for description. 254 */ 255 const char *text_domain; 256 257 /* 258 * free all class-related resources 259 */ 260 261 void (*dispose) (audio_driver_class_t *); 262 }; 263 264 #define default_audio_driver_class_dispose (void (*) (audio_driver_class_t *this_gen))free 265 266 /** 267 * @brief Initialise the audio_out sync routines 268 * 269 * @internal 270 */ 271 xine_audio_port_t *_x_ao_new_port (xine_t *xine, ao_driver_t *driver, int grab_only) XINE_MALLOC; 272 273 /* 274 * audio output modes + capabilities 275 */ 276 277 #define AO_CAP_NOCAP 0x00000000 /* driver has no capabilities */ 278 #define AO_CAP_MODE_A52 0x00000001 /* driver supports A/52 output */ 279 #define AO_CAP_MODE_AC5 0x00000002 /* driver supports AC5 output */ 280 /* 1 sample == 2 bytes (C) */ 281 #define AO_CAP_MODE_MONO 0x00000004 /* driver supports mono output */ 282 /* 1 sample == 4 bytes (L,R) */ 283 #define AO_CAP_MODE_STEREO 0x00000008 /* driver supports stereo output */ 284 /* 1 sample == 8 bytes (L,R,LR,RR) */ 285 #define AO_CAP_MODE_4CHANNEL 0x00000010 /* driver supports 4 channels */ 286 /* 287 * Sound cards generally support, 1,2,4,6 channels, but rarely 5. 288 * So xine will take 4.1, 5 and 6 channel a52 streams and 289 * down or upmix it correctly to fill the 6 output channels. 290 * Are there any requests for 2.1 out there? 291 */ 292 /* 1 sample == 12 bytes (L,R,LR,RR,Null,LFE) */ 293 #define AO_CAP_MODE_4_1CHANNEL 0x00000020 /* driver supports 4.1 channels */ 294 /* 1 sample == 12 bytes (L,R,LR,RR,C, Null) */ 295 #define AO_CAP_MODE_5CHANNEL 0x00000040 /* driver supports 5 channels */ 296 /* 1 sample == 12 bytes (L,R,LR,RR,C,LFE) */ 297 #define AO_CAP_MODE_5_1CHANNEL 0x00000080 /* driver supports 5.1 channels */ 298 299 /* 300 * converts the audio output mode into the number of channels 301 */ 302 int _x_ao_mode2channels( int mode ) XINE_PROTECTED; 303 /* 304 * converts the number of channels into the audio output mode 305 */ 306 int _x_ao_channels2mode( int channels ) XINE_PROTECTED; 307 308 #define AO_CAP_MIXER_VOL 0x00000100 /* driver supports mixer control */ 309 #define AO_CAP_PCM_VOL 0x00000200 /* driver supports pcm control */ 310 #define AO_CAP_MUTE_VOL 0x00000400 /* driver can mute volume */ 311 #define AO_CAP_8BITS 0x00000800 /* driver support 8-bit samples */ 312 #define AO_CAP_16BITS 0x00001000 /* driver support 16-bit samples */ 313 #define AO_CAP_24BITS 0x00002000 /* driver support 24-bit samples */ 314 #define AO_CAP_FLOAT32 0x00004000 /* driver support 32-bit samples. i.e. Floats */ 315 #define AO_CAP_NO_UNPAUSE 0x00008000 /* driver can not resume after pause. 316 * please resend some frames instead. */ 317 318 /* properties supported by get/set_property() */ 319 #define AO_PROP_MIXER_VOL 0 320 #define AO_PROP_PCM_VOL 1 321 #define AO_PROP_MUTE_VOL 2 322 #define AO_PROP_COMPRESSOR 3 323 #define AO_PROP_DISCARD_BUFFERS 4 324 #define AO_PROP_BUFS_IN_FIFO 5 /* read-only */ 325 #define AO_PROP_AMP 6 /* amplifier */ 326 #define AO_PROP_EQ_30HZ 7 /* equalizer */ 327 #define AO_PROP_EQ_60HZ 8 /* equalizer */ 328 #define AO_PROP_EQ_125HZ 9 /* equalizer */ 329 #define AO_PROP_EQ_250HZ 10 /* equalizer */ 330 #define AO_PROP_EQ_500HZ 11 /* equalizer */ 331 #define AO_PROP_EQ_1000HZ 12 /* equalizer */ 332 #define AO_PROP_EQ_2000HZ 13 /* equalizer */ 333 #define AO_PROP_EQ_4000HZ 14 /* equalizer */ 334 #define AO_PROP_EQ_8000HZ 15 /* equalizer */ 335 #define AO_PROP_EQ_16000HZ 16 /* equalizer */ 336 #define AO_PROP_CLOSE_DEVICE 17 /* force closing audio device */ 337 #define AO_PROP_AMP_MUTE 18 /* amplifier mute */ 338 #define AO_PROP_NUM_STREAMS 19 /* read-only */ 339 #define AO_PROP_CLOCK_SPEED 20 /* inform audio_out that speed has changed */ 340 #define AO_PROP_BUFS_TOTAL 21 /* read-only */ 341 #define AO_PROP_BUFS_FREE 22 /* read-only */ 342 #define AO_PROP_DRIVER_DELAY 23 /* read-only */ 343 #define AO_PROP_PTS_IN_FIFO 24 /* read only */ 344 #define AO_NUM_PROPERTIES 25 345 346 /* audio device control ops */ 347 #define AO_CTRL_PLAY_PAUSE 0 348 #define AO_CTRL_PLAY_RESUME 1 349 #define AO_CTRL_FLUSH_BUFFERS 2 350 351 /* above that value audio frames are discarded */ 352 #define AO_MAX_GAP 15000 353 354 #ifdef __cplusplus 355 } 356 #endif 357 358 #endif 359