xine-lib  1.2.10
audio_out.h
Go to the documentation of this file.
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 
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 
143 
145 
147 
148  int16_t *mem;
149  int mem_size;
151 
152  int64_t vpts;
155 
156  /* extra info coming from input or demuxers */
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 
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 */
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 */
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  */
221 
222  /*
223  * Check if port is opened for this stream and get parameters.
224  * The stream can be anonymous.
225  */
227  uint32_t *bits, uint32_t *rate, int *mode);
228 
229 };
230 
232 
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 
243  const char *identifier;
244 
250  const char *description;
251 
255  const char *text_domain;
256 
257  /*
258  * free all class-related resources
259  */
260 
262 };
263 
264 #define default_audio_driver_class_dispose (void (*) (audio_driver_class_t *this_gen))free
265 
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  */
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
xine_s
Definition: xine_internal.h:80
audio_buffer_s::num_frames
int num_frames
Definition: audio_out.h:150
audio_driver_class_s::dispose
void(* dispose)(audio_driver_class_t *)
Definition: audio_out.h:261
ao_format_s::mode
int mode
Definition: audio_out.h:137
ao_driver_s::write
int(* write)(ao_driver_t *, int16_t *audio_data, uint32_t num_samples)
Definition: audio_out.h:88
xine_stream_s
Definition: xine_internal.h:123
XINE_MALLOC
#define XINE_MALLOC
Definition: attributes.h:139
ao_driver_s::get_capabilities
uint32_t(* get_capabilities)(ao_driver_t *)
Definition: audio_out.h:52
xine_audio_port_s::status
int(* status)(xine_audio_port_t *, xine_stream_t *stream, uint32_t *bits, uint32_t *rate, int *mode)
Definition: audio_out.h:226
xineutils.h
xine_audio_port_s::close
void(* close)(xine_audio_port_t *self, xine_stream_t *stream)
Definition: audio_out.h:205
ao_driver_s::set_property
int(* set_property)(ao_driver_t *, int property, int value)
Definition: audio_out.h:113
audio_buffer_s::mem_size
int mem_size
Definition: audio_out.h:149
audio_buffer_s
Definition: audio_out.h:144
audio_driver_class_s::description
const char * description
human readable (verbose = 1 line) description for this plugin class
Definition: audio_out.h:250
xine_audio_port_s::set_property
int(* set_property)(xine_audio_port_t *, int property, int value)
Definition: audio_out.h:180
audio_driver_class_s::text_domain
const char * text_domain
Optional non-standard catalog to use with dgettext() for description.
Definition: audio_out.h:255
audio_buffer_s::mem
int16_t * mem
Definition: audio_out.h:148
audio_buffer_s::first_access_unit
uint32_t first_access_unit
Definition: audio_out.h:154
attributes.h
ao_format_s::rate
uint32_t rate
Definition: audio_out.h:136
ao_driver_s::XINE_PRIVATE_FIELD
struct plugin_node_s *node XINE_PRIVATE_FIELD
Pointer to the loaded plugin node.
Definition: audio_out.h:129
ao_driver_s::delay
int(* delay)(ao_driver_t *self_gen)
Definition: audio_out.h:74
audio_buffer_s::extra_info
extra_info_t * extra_info
Definition: audio_out.h:157
ao_driver_s::control
int(* control)(ao_driver_t *, int cmd,...)
Definition: audio_out.h:121
ao_driver_s::exit
void(* exit)(ao_driver_t *)
Definition: audio_out.h:101
ao_driver_s::open
int(* open)(ao_driver_t *, uint32_t bits, uint32_t rate, int mode)
Definition: audio_out.h:60
audio_driver_class_s::identifier
const char * identifier
short human readable identifier for this plugin class
Definition: audio_out.h:243
xine_audio_port_s::exit
void(* exit)(xine_audio_port_t *)
Definition: audio_out.h:208
xine_audio_port_s::control
int(* control)(xine_audio_port_t *, int cmd,...)
Definition: audio_out.h:215
xine_audio_port_s::open
int(* open)(xine_audio_port_t *, xine_stream_t *stream, uint32_t bits, uint32_t rate, int mode)
Definition: audio_out.h:187
xine_audio_port_s::get_property
int(* get_property)(xine_audio_port_t *, int property)
Definition: audio_out.h:179
audio_fifo_s
Definition: audio_out.c:188
audio_buffer_s::vpts
int64_t vpts
Definition: audio_out.h:152
buffer.h
audio_buffer_s::format
ao_format_t format
Definition: audio_out.h:161
ao_driver_s::num_channels
int(* num_channels)(ao_driver_t *self_gen)
Definition: audio_out.h:64
ao_driver_s::bytes_per_frame
int(* bytes_per_frame)(ao_driver_t *self_gen)
Definition: audio_out.h:69
os_types.h
ao_driver_s
Definition: audio_out.h:43
ao_driver_s::get_property
int(* get_property)(ao_driver_t *, int property)
Definition: audio_out.h:111
xine_audio_port_s
Definition: audio_out.h:172
mode
enable disable number of frames of telecine pattern sync required before mode change make frames evenly spaced for film mode(24 fps)" ) PARAM_ITEM( POST_PARAM_TYPE_BOOL
xine_audio_port_s::put_buffer
void(* put_buffer)(xine_audio_port_t *, audio_buffer_t *buf, xine_stream_t *stream)
Definition: audio_out.h:200
extra_info_s
Structure to pass information from input or demuxer plugins to output frames (past decoder).
Definition: buffer.h:317
ao_driver_s::get_gap_tolerance
int(* get_gap_tolerance)(ao_driver_t *self_gen)
Definition: audio_out.h:79
_x_ao_new_port
xine_audio_port_t * _x_ao_new_port(xine_t *xine, ao_driver_t *driver, int grab_only)
Initialise the audio_out sync routines.
Definition: audio_out.c:2764
XINE_PROTECTED
#define XINE_PROTECTED
Definition: attributes.h:73
plugin_node_s
Definition: plugin_catalog.h:44
xine_audio_port_s::get_capabilities
uint32_t(* get_capabilities)(xine_audio_port_t *)
Definition: audio_out.h:173
audio_driver_class_s
Definition: audio_out.h:233
_x_ao_channels2mode
int _x_ao_channels2mode(int channels)
Definition: audio_out.c:1098
ao_format_s::bits
uint32_t bits
Definition: audio_out.h:135
audio_buffer_s::frame_header_count
uint32_t frame_header_count
Definition: audio_out.h:153
xine_audio_port_s::flush
void(* flush)(xine_audio_port_t *)
Definition: audio_out.h:220
audio_buffer_s::stream
xine_stream_t * stream
Definition: audio_out.h:159
ao_driver_s::close
void(* close)(ao_driver_t *)
Definition: audio_out.h:95
audio_buffer_s::next
audio_buffer_t * next
Definition: audio_out.h:146
ao_format_s
Definition: audio_out.h:134
_x_ao_mode2channels
int _x_ao_mode2channels(int mode)
Definition: audio_out.c:1082
bits
#define bits