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

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