1/* GStreamer
2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2005 Wim Taymans <wim@fluendo.com>
4 *
5 * gstaudioringbuffer.h:
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef __GST_AUDIO_AUDIO_H__
24#include <gst/audio/audio.h>
25#endif
26
27#ifndef __GST_AUDIO_RING_BUFFER_H__
28#define __GST_AUDIO_RING_BUFFER_H__
29
30G_BEGIN_DECLS
31
32#define GST_TYPE_AUDIO_RING_BUFFER (gst_audio_ring_buffer_get_type())
33#define GST_AUDIO_RING_BUFFER(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AUDIO_RING_BUFFER,GstAudioRingBuffer))
34#define GST_AUDIO_RING_BUFFER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AUDIO_RING_BUFFER,GstAudioRingBufferClass))
35#define GST_AUDIO_RING_BUFFER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_AUDIO_RING_BUFFER, GstAudioRingBufferClass))
36#define GST_AUDIO_RING_BUFFER_CAST(obj) ((GstAudioRingBuffer *)obj)
37#define GST_IS_AUDIO_RING_BUFFER(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AUDIO_RING_BUFFER))
38#define GST_IS_AUDIO_RING_BUFFER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AUDIO_RING_BUFFER))
39
40typedef struct _GstAudioRingBuffer GstAudioRingBuffer;
41typedef struct _GstAudioRingBufferClass GstAudioRingBufferClass;
42typedef struct _GstAudioRingBufferSpec GstAudioRingBufferSpec;
43
44/**
45 * GstAudioRingBufferCallback:
46 * @rbuf: a #GstAudioRingBuffer
47 * @data: (array length=len): target to fill
48 * @len: amount to fill
49 * @user_data: user data
50 *
51 * This function is set with gst_audio_ring_buffer_set_callback() and is
52 * called to fill the memory at @data with @len bytes of samples.
53 */
54typedef void (*GstAudioRingBufferCallback) (GstAudioRingBuffer *rbuf, guint8* data, guint len, gpointer user_data);
55
56/**
57 * GstAudioRingBufferState:
58 * @GST_AUDIO_RING_BUFFER_STATE_STOPPED: The ringbuffer is stopped
59 * @GST_AUDIO_RING_BUFFER_STATE_PAUSED: The ringbuffer is paused
60 * @GST_AUDIO_RING_BUFFER_STATE_STARTED: The ringbuffer is started
61 * @GST_AUDIO_RING_BUFFER_STATE_ERROR: The ringbuffer has encountered an
62 * error after it has been started, e.g. because the device was
63 * disconnected (Since 1.2)
64 *
65 * The state of the ringbuffer.
66 */
67typedef enum {
68 GST_AUDIO_RING_BUFFER_STATE_STOPPED,
69 GST_AUDIO_RING_BUFFER_STATE_PAUSED,
70 GST_AUDIO_RING_BUFFER_STATE_STARTED,
71 GST_AUDIO_RING_BUFFER_STATE_ERROR
72} GstAudioRingBufferState;
73
74/**
75 * GstAudioRingBufferFormatType:
76 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_RAW: samples in linear or float
77 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MU_LAW: samples in mulaw
78 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_A_LAW: samples in alaw
79 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IMA_ADPCM: samples in ima adpcm
80 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG: samples in mpeg audio (but not AAC) format
81 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_GSM: samples in gsm format
82 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IEC958: samples in IEC958 frames (e.g. AC3)
83 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_AC3: samples in AC3 format
84 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_EAC3: samples in EAC3 format
85 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DTS: samples in DTS format
86 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC: samples in MPEG-2 AAC ADTS format
87 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC: samples in MPEG-4 AAC ADTS format
88 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC_RAW: samples in MPEG-2 AAC raw format (Since 1.12)
89 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC_RAW: samples in MPEG-4 AAC raw format (Since 1.12)
90 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_FLAC: samples in FLAC format (Since 1.12)
91 *
92 * The format of the samples in the ringbuffer.
93 */
94typedef enum
95{
96 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_RAW,
97 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MU_LAW,
98 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_A_LAW,
99 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IMA_ADPCM,
100 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG,
101 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_GSM,
102 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IEC958,
103 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_AC3,
104 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_EAC3,
105 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DTS,
106 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC,
107 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC,
108 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC_RAW,
109 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC_RAW,
110 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_FLAC
111} GstAudioRingBufferFormatType;
112
113/**
114 * GstAudioRingBufferSpec:
115 * @caps: The caps that generated the Spec.
116 * @type: the sample type
117 * @info: the #GstAudioInfo
118 * @latency_time: the latency in microseconds
119 * @buffer_time: the total buffer size in microseconds
120 * @segsize: the size of one segment in bytes
121 * @segtotal: the total number of segments
122 * @seglatency: number of segments queued in the lower level device,
123 * defaults to segtotal
124 *
125 * The structure containing the format specification of the ringbuffer.
126 */
127struct _GstAudioRingBufferSpec
128{
129 /*< public >*/
130 /* in */
131 GstCaps *caps; /* the caps of the buffer */
132
133 /* in/out */
134 GstAudioRingBufferFormatType type;
135 GstAudioInfo info;
136
137
138 guint64 latency_time; /* the required/actual latency time, this is the
139 * actual the size of one segment and the
140 * minimum possible latency we can achieve. */
141 guint64 buffer_time; /* the required/actual time of the buffer, this is
142 * the total size of the buffer and maximum
143 * latency we can compensate for. */
144 gint segsize; /* size of one buffer segment in bytes, this value
145 * should be chosen to match latency_time as
146 * well as possible. */
147 gint segtotal; /* total number of segments, this value is the
148 * number of segments of @segsize and should be
149 * chosen so that it matches buffer_time as
150 * close as possible. */
151 /* ABI added 0.10.20 */
152 gint seglatency; /* number of segments queued in the lower
153 * level device, defaults to segtotal. */
154
155 /*< private >*/
156 gpointer _gst_reserved[GST_PADDING];
157};
158
159#define GST_AUDIO_RING_BUFFER_GET_COND(buf) (&(((GstAudioRingBuffer *)buf)->cond))
160#define GST_AUDIO_RING_BUFFER_WAIT(buf) (g_cond_wait (GST_AUDIO_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))
161#define GST_AUDIO_RING_BUFFER_SIGNAL(buf) (g_cond_signal (GST_AUDIO_RING_BUFFER_GET_COND (buf)))
162#define GST_AUDIO_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_AUDIO_RING_BUFFER_GET_COND (buf)))
163
164/**
165 * GstAudioRingBuffer:
166 * @cond: used to signal start/stop/pause/resume actions
167 * @open: boolean indicating that the ringbuffer is open
168 * @acquired: boolean indicating that the ringbuffer is acquired
169 * @memory: data in the ringbuffer
170 * @size: size of data in the ringbuffer
171 * @spec: format and layout of the ringbuffer data
172 * @samples_per_seg: number of samples in one segment
173 * @empty_seg: pointer to memory holding one segment of silence samples
174 * @state: state of the buffer
175 * @segdone: readpointer in the ringbuffer
176 * @segbase: segment corresponding to segment 0 (unused)
177 * @waiting: is a reader or writer waiting for a free segment
178 *
179 * The ringbuffer base class structure.
180 */
181struct _GstAudioRingBuffer {
182 GstObject object;
183
184 /*< public >*/ /* with LOCK */
185 GCond cond;
186 gboolean open;
187 gboolean acquired;
188 guint8 *memory;
189 gsize size;
190 /*< private >*/
191 GstClockTime *timestamps;
192 /*< public >*/ /* with LOCK */
193 GstAudioRingBufferSpec spec;
194 gint samples_per_seg;
195 guint8 *empty_seg;
196
197 /*< public >*/ /* ATOMIC */
198 gint state;
199 gint segdone;
200 gint segbase;
201 gint waiting;
202
203 /*< private >*/
204 GstAudioRingBufferCallback callback;
205 gpointer cb_data;
206
207 gboolean need_reorder;
208 /* gst[channel_reorder_map[i]] = device[i] */
209 gint channel_reorder_map[64];
210
211 gboolean flushing;
212 /* ATOMIC */
213 gint may_start;
214 gboolean active;
215
216 GDestroyNotify cb_data_notify;
217
218 /*< private >*/
219 gpointer _gst_reserved[GST_PADDING - 1];
220};
221
222/**
223 * GstAudioRingBufferClass:
224 * @parent_class: parent class
225 * @open_device: open the device, don't set any params or allocate anything
226 * @acquire: allocate the resources for the ringbuffer using the given spec
227 * @release: free resources of the ringbuffer
228 * @close_device: close the device
229 * @start: start processing of samples
230 * @pause: pause processing of samples
231 * @resume: resume processing of samples after pause
232 * @stop: stop processing of samples
233 * @delay: get number of frames queued in device
234 * @activate: activate the thread that starts pulling and monitoring the
235 * consumed segments in the device.
236 * @commit: write samples into the ringbuffer
237 * @clear_all: clear the entire ringbuffer.
238 *
239 * The vmethods that subclasses can override to implement the ringbuffer.
240 */
241struct _GstAudioRingBufferClass {
242 GstObjectClass parent_class;
243
244 /*< public >*/
245 gboolean (*open_device) (GstAudioRingBuffer *buf);
246 gboolean (*acquire) (GstAudioRingBuffer *buf, GstAudioRingBufferSpec *spec);
247 gboolean (*release) (GstAudioRingBuffer *buf);
248 gboolean (*close_device) (GstAudioRingBuffer *buf);
249
250 gboolean (*start) (GstAudioRingBuffer *buf);
251 gboolean (*pause) (GstAudioRingBuffer *buf);
252 gboolean (*resume) (GstAudioRingBuffer *buf);
253 gboolean (*stop) (GstAudioRingBuffer *buf);
254
255 guint (*delay) (GstAudioRingBuffer *buf);
256
257 /* ABI added */
258 gboolean (*activate) (GstAudioRingBuffer *buf, gboolean active);
259
260 guint (*commit) (GstAudioRingBuffer * buf, guint64 *sample,
261 guint8 * data, gint in_samples,
262 gint out_samples, gint * accum);
263
264 void (*clear_all) (GstAudioRingBuffer * buf);
265
266 /*< private >*/
267 gpointer _gst_reserved[GST_PADDING];
268};
269
270GST_AUDIO_API
271GType gst_audio_ring_buffer_get_type(void);
272
273/* callback stuff */
274
275GST_AUDIO_API
276void gst_audio_ring_buffer_set_callback (GstAudioRingBuffer *buf,
277 GstAudioRingBufferCallback cb,
278 gpointer user_data);
279
280GST_AUDIO_API
281void gst_audio_ring_buffer_set_callback_full (GstAudioRingBuffer *buf,
282 GstAudioRingBufferCallback cb,
283 gpointer user_data,
284 GDestroyNotify notify);
285
286GST_AUDIO_API
287gboolean gst_audio_ring_buffer_parse_caps (GstAudioRingBufferSpec *spec, GstCaps *caps);
288
289GST_AUDIO_API
290void gst_audio_ring_buffer_debug_spec_caps (GstAudioRingBufferSpec *spec);
291
292GST_AUDIO_API
293void gst_audio_ring_buffer_debug_spec_buff (GstAudioRingBufferSpec *spec);
294
295GST_AUDIO_API
296gboolean gst_audio_ring_buffer_convert (GstAudioRingBuffer * buf, GstFormat src_fmt,
297 gint64 src_val, GstFormat dest_fmt,
298 gint64 * dest_val);
299
300/* device state */
301
302GST_AUDIO_API
303gboolean gst_audio_ring_buffer_open_device (GstAudioRingBuffer *buf);
304
305GST_AUDIO_API
306gboolean gst_audio_ring_buffer_close_device (GstAudioRingBuffer *buf);
307
308GST_AUDIO_API
309gboolean gst_audio_ring_buffer_device_is_open (GstAudioRingBuffer *buf);
310
311/* allocate resources */
312
313GST_AUDIO_API
314gboolean gst_audio_ring_buffer_acquire (GstAudioRingBuffer *buf, GstAudioRingBufferSpec *spec);
315
316GST_AUDIO_API
317gboolean gst_audio_ring_buffer_release (GstAudioRingBuffer *buf);
318
319GST_AUDIO_API
320gboolean gst_audio_ring_buffer_is_acquired (GstAudioRingBuffer *buf);
321
322/* set the device channel positions */
323
324GST_AUDIO_API
325void gst_audio_ring_buffer_set_channel_positions (GstAudioRingBuffer *buf, const GstAudioChannelPosition *position);
326
327/* activating */
328
329GST_AUDIO_API
330gboolean gst_audio_ring_buffer_activate (GstAudioRingBuffer *buf, gboolean active);
331
332GST_AUDIO_API
333gboolean gst_audio_ring_buffer_is_active (GstAudioRingBuffer *buf);
334
335/* flushing */
336
337GST_AUDIO_API
338void gst_audio_ring_buffer_set_flushing (GstAudioRingBuffer *buf, gboolean flushing);
339
340GST_AUDIO_API
341gboolean gst_audio_ring_buffer_is_flushing (GstAudioRingBuffer *buf);
342
343/* playback/pause */
344
345GST_AUDIO_API
346gboolean gst_audio_ring_buffer_start (GstAudioRingBuffer *buf);
347
348GST_AUDIO_API
349gboolean gst_audio_ring_buffer_pause (GstAudioRingBuffer *buf);
350
351GST_AUDIO_API
352gboolean gst_audio_ring_buffer_stop (GstAudioRingBuffer *buf);
353
354/* get status */
355
356GST_AUDIO_API
357guint gst_audio_ring_buffer_delay (GstAudioRingBuffer *buf);
358
359GST_AUDIO_API
360guint64 gst_audio_ring_buffer_samples_done (GstAudioRingBuffer *buf);
361
362GST_AUDIO_API
363void gst_audio_ring_buffer_set_sample (GstAudioRingBuffer *buf, guint64 sample);
364
365/* clear all segments */
366
367GST_AUDIO_API
368void gst_audio_ring_buffer_clear_all (GstAudioRingBuffer *buf);
369
370/* commit samples */
371
372GST_AUDIO_API
373guint gst_audio_ring_buffer_commit (GstAudioRingBuffer * buf, guint64 *sample,
374 guint8 * data, gint in_samples,
375 gint out_samples, gint * accum);
376
377/* read samples */
378
379GST_AUDIO_API
380guint gst_audio_ring_buffer_read (GstAudioRingBuffer *buf, guint64 sample,
381 guint8 *data, guint len, GstClockTime *timestamp);
382
383/* Set timestamp on buffer */
384
385GST_AUDIO_API
386void gst_audio_ring_buffer_set_timestamp (GstAudioRingBuffer * buf, gint readseg, GstClockTime
387 timestamp);
388
389/* mostly protected */
390/* not yet implemented
391gboolean gst_audio_ring_buffer_prepare_write (GstAudioRingBuffer *buf, gint *segment, guint8 **writeptr, gint *len);
392*/
393
394GST_AUDIO_API
395gboolean gst_audio_ring_buffer_prepare_read (GstAudioRingBuffer *buf, gint *segment,
396 guint8 **readptr, gint *len);
397
398GST_AUDIO_API
399void gst_audio_ring_buffer_clear (GstAudioRingBuffer *buf, gint segment);
400
401GST_AUDIO_API
402void gst_audio_ring_buffer_advance (GstAudioRingBuffer *buf, guint advance);
403
404GST_AUDIO_API
405void gst_audio_ring_buffer_may_start (GstAudioRingBuffer *buf, gboolean allowed);
406
407#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
408G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAudioRingBuffer, gst_object_unref)
409#endif
410
411G_END_DECLS
412
413#endif /* __GST_AUDIO_RING_BUFFER_H__ */
414