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: Optional.
238 * Clear the entire ringbuffer.
239 * Subclasses should chain up to the parent implementation to
240 * invoke the default handler.
241 *
242 * The vmethods that subclasses can override to implement the ringbuffer.
243 */
244struct _GstAudioRingBufferClass {
245 GstObjectClass parent_class;
246
247 /*< public >*/
248 gboolean (*open_device) (GstAudioRingBuffer *buf);
249 gboolean (*acquire) (GstAudioRingBuffer *buf, GstAudioRingBufferSpec *spec);
250 gboolean (*release) (GstAudioRingBuffer *buf);
251 gboolean (*close_device) (GstAudioRingBuffer *buf);
252
253 gboolean (*start) (GstAudioRingBuffer *buf);
254 gboolean (*pause) (GstAudioRingBuffer *buf);
255 gboolean (*resume) (GstAudioRingBuffer *buf);
256 gboolean (*stop) (GstAudioRingBuffer *buf);
257
258 guint (*delay) (GstAudioRingBuffer *buf);
259
260 /* ABI added */
261 gboolean (*activate) (GstAudioRingBuffer *buf, gboolean active);
262
263 guint (*commit) (GstAudioRingBuffer * buf, guint64 *sample,
264 guint8 * data, gint in_samples,
265 gint out_samples, gint * accum);
266
267 void (*clear_all) (GstAudioRingBuffer * buf);
268
269 /*< private >*/
270 gpointer _gst_reserved[GST_PADDING];
271};
272
273GST_AUDIO_API
274GType gst_audio_ring_buffer_get_type(void);
275
276/* callback stuff */
277
278GST_AUDIO_API
279void gst_audio_ring_buffer_set_callback (GstAudioRingBuffer *buf,
280 GstAudioRingBufferCallback cb,
281 gpointer user_data);
282
283GST_AUDIO_API
284void gst_audio_ring_buffer_set_callback_full (GstAudioRingBuffer *buf,
285 GstAudioRingBufferCallback cb,
286 gpointer user_data,
287 GDestroyNotify notify);
288
289GST_AUDIO_API
290gboolean gst_audio_ring_buffer_parse_caps (GstAudioRingBufferSpec *spec, GstCaps *caps);
291
292GST_AUDIO_API
293void gst_audio_ring_buffer_debug_spec_caps (GstAudioRingBufferSpec *spec);
294
295GST_AUDIO_API
296void gst_audio_ring_buffer_debug_spec_buff (GstAudioRingBufferSpec *spec);
297
298GST_AUDIO_API
299gboolean gst_audio_ring_buffer_convert (GstAudioRingBuffer * buf, GstFormat src_fmt,
300 gint64 src_val, GstFormat dest_fmt,
301 gint64 * dest_val);
302
303/* device state */
304
305GST_AUDIO_API
306gboolean gst_audio_ring_buffer_open_device (GstAudioRingBuffer *buf);
307
308GST_AUDIO_API
309gboolean gst_audio_ring_buffer_close_device (GstAudioRingBuffer *buf);
310
311GST_AUDIO_API
312gboolean gst_audio_ring_buffer_device_is_open (GstAudioRingBuffer *buf);
313
314/* allocate resources */
315
316GST_AUDIO_API
317gboolean gst_audio_ring_buffer_acquire (GstAudioRingBuffer *buf, GstAudioRingBufferSpec *spec);
318
319GST_AUDIO_API
320gboolean gst_audio_ring_buffer_release (GstAudioRingBuffer *buf);
321
322GST_AUDIO_API
323gboolean gst_audio_ring_buffer_is_acquired (GstAudioRingBuffer *buf);
324
325/* set the device channel positions */
326
327GST_AUDIO_API
328void gst_audio_ring_buffer_set_channel_positions (GstAudioRingBuffer *buf, const GstAudioChannelPosition *position);
329
330/* activating */
331
332GST_AUDIO_API
333gboolean gst_audio_ring_buffer_activate (GstAudioRingBuffer *buf, gboolean active);
334
335GST_AUDIO_API
336gboolean gst_audio_ring_buffer_is_active (GstAudioRingBuffer *buf);
337
338/* flushing */
339
340GST_AUDIO_API
341void gst_audio_ring_buffer_set_flushing (GstAudioRingBuffer *buf, gboolean flushing);
342
343GST_AUDIO_API
344gboolean gst_audio_ring_buffer_is_flushing (GstAudioRingBuffer *buf);
345
346/* playback/pause */
347
348GST_AUDIO_API
349gboolean gst_audio_ring_buffer_start (GstAudioRingBuffer *buf);
350
351GST_AUDIO_API
352gboolean gst_audio_ring_buffer_pause (GstAudioRingBuffer *buf);
353
354GST_AUDIO_API
355gboolean gst_audio_ring_buffer_stop (GstAudioRingBuffer *buf);
356
357/* get status */
358
359GST_AUDIO_API
360guint gst_audio_ring_buffer_delay (GstAudioRingBuffer *buf);
361
362GST_AUDIO_API
363guint64 gst_audio_ring_buffer_samples_done (GstAudioRingBuffer *buf);
364
365GST_AUDIO_API
366void gst_audio_ring_buffer_set_sample (GstAudioRingBuffer *buf, guint64 sample);
367
368/* clear all segments */
369
370GST_AUDIO_API
371void gst_audio_ring_buffer_clear_all (GstAudioRingBuffer *buf);
372
373/* commit samples */
374
375GST_AUDIO_API
376guint gst_audio_ring_buffer_commit (GstAudioRingBuffer * buf, guint64 *sample,
377 guint8 * data, gint in_samples,
378 gint out_samples, gint * accum);
379
380/* read samples */
381
382GST_AUDIO_API
383guint gst_audio_ring_buffer_read (GstAudioRingBuffer *buf, guint64 sample,
384 guint8 *data, guint len, GstClockTime *timestamp);
385
386/* Set timestamp on buffer */
387
388GST_AUDIO_API
389void gst_audio_ring_buffer_set_timestamp (GstAudioRingBuffer * buf, gint readseg, GstClockTime
390 timestamp);
391
392/* mostly protected */
393/* not yet implemented
394gboolean gst_audio_ring_buffer_prepare_write (GstAudioRingBuffer *buf, gint *segment, guint8 **writeptr, gint *len);
395*/
396
397GST_AUDIO_API
398gboolean gst_audio_ring_buffer_prepare_read (GstAudioRingBuffer *buf, gint *segment,
399 guint8 **readptr, gint *len);
400
401GST_AUDIO_API
402void gst_audio_ring_buffer_clear (GstAudioRingBuffer *buf, gint segment);
403
404GST_AUDIO_API
405void gst_audio_ring_buffer_advance (GstAudioRingBuffer *buf, guint advance);
406
407GST_AUDIO_API
408void gst_audio_ring_buffer_may_start (GstAudioRingBuffer *buf, gboolean allowed);
409
410G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAudioRingBuffer, gst_object_unref)
411
412G_END_DECLS
413
414#endif /* __GST_AUDIO_RING_BUFFER_H__ */
415

source code of include/gstreamer-1.0/gst/audio/gstaudioringbuffer.h