2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2005 Wim Taymans <wim@fluendo.com>
5 * gstaudioringbuffer.h:
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.
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.
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.
23 #ifndef __GST_AUDIO_RING_BUFFER_H__
24 #define __GST_AUDIO_RING_BUFFER_H__
27 #include <gst/audio/audio.h>
31 #define GST_TYPE_AUDIO_RING_BUFFER (gst_audio_ring_buffer_get_type())
32 #define GST_AUDIO_RING_BUFFER(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AUDIO_RING_BUFFER,GstAudioRingBuffer))
33 #define GST_AUDIO_RING_BUFFER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AUDIO_RING_BUFFER,GstAudioRingBufferClass))
34 #define GST_AUDIO_RING_BUFFER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_AUDIO_RING_BUFFER, GstAudioRingBufferClass))
35 #define GST_AUDIO_RING_BUFFER_CAST(obj) ((GstAudioRingBuffer *)obj)
36 #define GST_IS_AUDIO_RING_BUFFER(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AUDIO_RING_BUFFER))
37 #define GST_IS_AUDIO_RING_BUFFER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AUDIO_RING_BUFFER))
39 typedef struct _GstAudioRingBuffer GstAudioRingBuffer;
40 typedef struct _GstAudioRingBufferClass GstAudioRingBufferClass;
41 typedef struct _GstAudioRingBufferSpec GstAudioRingBufferSpec;
44 * GstAudioRingBufferCallback:
45 * @rbuf: a #GstAudioRingBuffer
46 * @data: (array length=len): target to fill
47 * @len: amount to fill
48 * @user_data: user data
50 * This function is set with gst_audio_ring_buffer_set_callback() and is
51 * called to fill the memory at @data with @len bytes of samples.
53 typedef void (*GstAudioRingBufferCallback) (GstAudioRingBuffer *rbuf, guint8* data, guint len, gpointer user_data);
56 * GstAudioRingBufferState:
57 * @GST_AUDIO_RING_BUFFER_STATE_STOPPED: The ringbuffer is stopped
58 * @GST_AUDIO_RING_BUFFER_STATE_PAUSED: The ringbuffer is paused
59 * @GST_AUDIO_RING_BUFFER_STATE_STARTED: The ringbuffer is started
60 * @GST_AUDIO_RING_BUFFER_STATE_ERROR: The ringbuffer has encountered an
61 * error after it has been started, e.g. because the device was
62 * disconnected (Since 1.2)
64 * The state of the ringbuffer.
67 GST_AUDIO_RING_BUFFER_STATE_STOPPED,
68 GST_AUDIO_RING_BUFFER_STATE_PAUSED,
69 GST_AUDIO_RING_BUFFER_STATE_STARTED,
70 GST_AUDIO_RING_BUFFER_STATE_ERROR
71 } GstAudioRingBufferState;
74 * GstAudioRingBufferFormatType:
75 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_RAW: samples in linear or float
76 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MU_LAW: samples in mulaw
77 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_A_LAW: samples in alaw
78 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IMA_ADPCM: samples in ima adpcm
79 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG: samples in mpeg audio (but not AAC) format
80 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_GSM: samples in gsm format
81 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IEC958: samples in IEC958 frames (e.g. AC3)
82 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_AC3: samples in AC3 format
83 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_EAC3: samples in EAC3 format
84 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DTS: samples in DTS format
85 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC: samples in MPEG-2 AAC format
86 * @GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC: samples in MPEG-4 AAC format
88 * The format of the samples in the ringbuffer.
92 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_RAW,
93 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MU_LAW,
94 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_A_LAW,
95 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IMA_ADPCM,
96 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG,
97 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_GSM,
98 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IEC958,
99 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_AC3,
100 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_EAC3,
101 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DTS,
102 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC,
103 GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC
104 } GstAudioRingBufferFormatType;
107 * GstAudioRingBufferSpec:
108 * @caps: The caps that generated the Spec.
109 * @type: the sample type
110 * @info: the #GstAudioInfo
111 * @latency_time: the latency in microseconds
112 * @buffer_time: the total buffer size in microseconds
113 * @segsize: the size of one segment in bytes
114 * @segtotal: the total number of segments
115 * @seglatency: number of segments queued in the lower level device,
116 * defaults to segtotal
118 * The structure containing the format specification of the ringbuffer.
120 struct _GstAudioRingBufferSpec
124 GstCaps *caps; /* the caps of the buffer */
127 GstAudioRingBufferFormatType type;
131 guint64 latency_time; /* the required/actual latency time, this is the
132 * actual the size of one segment and the
133 * minimum possible latency we can achieve. */
134 guint64 buffer_time; /* the required/actual time of the buffer, this is
135 * the total size of the buffer and maximum
136 * latency we can compensate for. */
137 gint segsize; /* size of one buffer segment in bytes, this value
138 * should be chosen to match latency_time as
139 * well as possible. */
140 gint segtotal; /* total number of segments, this value is the
141 * number of segments of @segsize and should be
142 * chosen so that it matches buffer_time as
143 * close as possible. */
144 /* ABI added 0.10.20 */
145 gint seglatency; /* number of segments queued in the lower
146 * level device, defaults to segtotal. */
149 gpointer _gst_reserved[GST_PADDING];
152 #define GST_AUDIO_RING_BUFFER_GET_COND(buf) (&(((GstAudioRingBuffer *)buf)->cond))
153 #define GST_AUDIO_RING_BUFFER_WAIT(buf) (g_cond_wait (GST_AUDIO_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))
154 #define GST_AUDIO_RING_BUFFER_SIGNAL(buf) (g_cond_signal (GST_AUDIO_RING_BUFFER_GET_COND (buf)))
155 #define GST_AUDIO_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_AUDIO_RING_BUFFER_GET_COND (buf)))
158 * GstAudioRingBuffer:
159 * @cond: used to signal start/stop/pause/resume actions
160 * @open: boolean indicating that the ringbuffer is open
161 * @acquired: boolean indicating that the ringbuffer is acquired
162 * @memory: data in the ringbuffer
163 * @size: size of data in the ringbuffer
164 * @spec: format and layout of the ringbuffer data
165 * @samples_per_seg: number of samples in one segment
166 * @empty_seg: pointer to memory holding one segment of silence samples
167 * @state: state of the buffer
168 * @segdone: readpointer in the ringbuffer
169 * @segbase: segment corresponding to segment 0 (unused)
170 * @waiting: is a reader or writer waiting for a free segment
172 * The ringbuffer base class structure.
174 struct _GstAudioRingBuffer {
177 /*< public >*/ /* with LOCK */
183 GstClockTime *timestamps;
184 GstAudioRingBufferSpec spec;
185 gint samples_per_seg;
188 /*< public >*/ /* ATOMIC */
195 GstAudioRingBufferCallback callback;
198 gboolean need_reorder;
199 /* gst[channel_reorder_map[i]] = device[i] */
200 gint channel_reorder_map[64];
208 gpointer _gst_reserved[GST_PADDING];
212 * GstAudioRingBufferClass:
213 * @parent_class: parent class
214 * @open_device: open the device, don't set any params or allocate anything
215 * @acquire: allocate the resources for the ringbuffer using the given spec
216 * @release: free resources of the ringbuffer
217 * @close_device: close the device
218 * @start: start processing of samples
219 * @pause: pause processing of samples
220 * @resume: resume processing of samples after pause
221 * @stop: stop processing of samples
222 * @delay: get number of samples queued in device
223 * @activate: activate the thread that starts pulling and monitoring the
224 * consumed segments in the device.
225 * @commit: write samples into the ringbuffer
226 * @clear_all: clear the entire ringbuffer.
228 * The vmethods that subclasses can override to implement the ringbuffer.
230 struct _GstAudioRingBufferClass {
231 GstObjectClass parent_class;
234 gboolean (*open_device) (GstAudioRingBuffer *buf);
235 gboolean (*acquire) (GstAudioRingBuffer *buf, GstAudioRingBufferSpec *spec);
236 gboolean (*release) (GstAudioRingBuffer *buf);
237 gboolean (*close_device) (GstAudioRingBuffer *buf);
239 gboolean (*start) (GstAudioRingBuffer *buf);
240 gboolean (*pause) (GstAudioRingBuffer *buf);
241 gboolean (*resume) (GstAudioRingBuffer *buf);
242 gboolean (*stop) (GstAudioRingBuffer *buf);
244 guint (*delay) (GstAudioRingBuffer *buf);
247 gboolean (*activate) (GstAudioRingBuffer *buf, gboolean active);
249 guint (*commit) (GstAudioRingBuffer * buf, guint64 *sample,
250 guint8 * data, gint in_samples,
251 gint out_samples, gint * accum);
253 void (*clear_all) (GstAudioRingBuffer * buf);
256 gpointer _gst_reserved[GST_PADDING];
259 GType gst_audio_ring_buffer_get_type(void);
262 void gst_audio_ring_buffer_set_callback (GstAudioRingBuffer *buf,
263 GstAudioRingBufferCallback cb,
266 gboolean gst_audio_ring_buffer_parse_caps (GstAudioRingBufferSpec *spec, GstCaps *caps);
267 void gst_audio_ring_buffer_debug_spec_caps (GstAudioRingBufferSpec *spec);
268 void gst_audio_ring_buffer_debug_spec_buff (GstAudioRingBufferSpec *spec);
270 gboolean gst_audio_ring_buffer_convert (GstAudioRingBuffer * buf, GstFormat src_fmt,
271 gint64 src_val, GstFormat dest_fmt,
275 gboolean gst_audio_ring_buffer_open_device (GstAudioRingBuffer *buf);
276 gboolean gst_audio_ring_buffer_close_device (GstAudioRingBuffer *buf);
278 gboolean gst_audio_ring_buffer_device_is_open (GstAudioRingBuffer *buf);
280 /* allocate resources */
281 gboolean gst_audio_ring_buffer_acquire (GstAudioRingBuffer *buf, GstAudioRingBufferSpec *spec);
282 gboolean gst_audio_ring_buffer_release (GstAudioRingBuffer *buf);
284 gboolean gst_audio_ring_buffer_is_acquired (GstAudioRingBuffer *buf);
286 /* set the device channel positions */
287 void gst_audio_ring_buffer_set_channel_positions (GstAudioRingBuffer *buf, const GstAudioChannelPosition *position);
290 gboolean gst_audio_ring_buffer_activate (GstAudioRingBuffer *buf, gboolean active);
291 gboolean gst_audio_ring_buffer_is_active (GstAudioRingBuffer *buf);
294 void gst_audio_ring_buffer_set_flushing (GstAudioRingBuffer *buf, gboolean flushing);
295 gboolean gst_audio_ring_buffer_is_flushing (GstAudioRingBuffer *buf);
298 gboolean gst_audio_ring_buffer_start (GstAudioRingBuffer *buf);
299 gboolean gst_audio_ring_buffer_pause (GstAudioRingBuffer *buf);
300 gboolean gst_audio_ring_buffer_stop (GstAudioRingBuffer *buf);
303 guint gst_audio_ring_buffer_delay (GstAudioRingBuffer *buf);
304 guint64 gst_audio_ring_buffer_samples_done (GstAudioRingBuffer *buf);
306 void gst_audio_ring_buffer_set_sample (GstAudioRingBuffer *buf, guint64 sample);
308 /* clear all segments */
309 void gst_audio_ring_buffer_clear_all (GstAudioRingBuffer *buf);
312 guint gst_audio_ring_buffer_commit (GstAudioRingBuffer * buf, guint64 *sample,
313 guint8 * data, gint in_samples,
314 gint out_samples, gint * accum);
317 guint gst_audio_ring_buffer_read (GstAudioRingBuffer *buf, guint64 sample,
318 guint8 *data, guint len, GstClockTime *timestamp);
320 /* Set timestamp on buffer */
321 void gst_audio_ring_buffer_set_timestamp (GstAudioRingBuffer * buf, gint readseg, GstClockTime
324 /* mostly protected */
325 /* not yet implemented
326 gboolean gst_audio_ring_buffer_prepare_write (GstAudioRingBuffer *buf, gint *segment, guint8 **writeptr, gint *len);
328 gboolean gst_audio_ring_buffer_prepare_read (GstAudioRingBuffer *buf, gint *segment,
329 guint8 **readptr, gint *len);
330 void gst_audio_ring_buffer_clear (GstAudioRingBuffer *buf, gint segment);
331 void gst_audio_ring_buffer_advance (GstAudioRingBuffer *buf, guint advance);
333 void gst_audio_ring_buffer_may_start (GstAudioRingBuffer *buf, gboolean allowed);
337 #endif /* __GST_AUDIO_RING_BUFFER_H__ */