This object is the base class for audio ringbuffers used by the base audio source and sink classes.

The ringbuffer abstracts a circular buffer of data. One reader and one writer can operate on the data from different threads in a lockfree manner. The base class is sufficiently flexible to be used as an abstraction for DMA based ringbuffers as well as a pure software implementations.

struct GstRingBuffer

struct GstRingBuffer {
  GCond                 *cond;
  gboolean               open;
  gboolean               acquired;
  GstBuffer             *data;
  GstRingBufferSpec      spec;
  GstRingBufferSegState *segstate;
  gint                   samples_per_seg;
  guint8                *empty_seg;

  gint                   state;
  gint                   segdone;
  gint                   segbase;
  gint                   waiting;
};

The ringbuffer base class structure.

struct GstRingBufferClass

struct GstRingBufferClass {
  GstObjectClass parent_class;

  gboolean     (*open_device)  (GstRingBuffer *buf);
  gboolean     (*acquire)      (GstRingBuffer *buf, GstRingBufferSpec *spec);
  gboolean     (*release)      (GstRingBuffer *buf);
  gboolean     (*close_device) (GstRingBuffer *buf);

  gboolean     (*start)        (GstRingBuffer *buf);
  gboolean     (*pause)        (GstRingBuffer *buf);
  gboolean     (*resume)       (GstRingBuffer *buf);
  gboolean     (*stop)         (GstRingBuffer *buf);

  guint        (*delay)        (GstRingBuffer *buf);

  /* ABI added */
  gboolean     (*activate)     (GstRingBuffer *buf, gboolean active);

  guint        (*commit)       (GstRingBuffer * buf, guint64 *sample,
                                guchar * data, gint in_samples,
                                gint out_samples, gint * accum);

  void         (*clear_all)    (GstRingBuffer * buf);
};

The vmethods that subclasses can override to implement the ringbuffer.

struct GstRingBufferSpec

struct GstRingBufferSpec {
  /* in */
  GstCaps  *caps;               /* the caps of the buffer */

  /* in/out */
  GstBufferFormatType   type;
  GstBufferFormat format;
  gboolean  sign;
  gboolean  bigend;
  gint      width;
  gint      depth;
  gint      rate;
  gint      channels;

  guint64  latency_time;        /* the required/actual latency time, this is the
				 * actual the size of one segment and the
				 * minimum possible latency we can achieve. */
  guint64  buffer_time;         /* the required/actual time of the buffer, this is
				 * the total size of the buffer and maximum
				 * latency we can compensate for. */
  gint     segsize;             /* size of one buffer segment in bytes, this value
				 * should be chosen to match latency_time as
				 * well as possible. */
  gint     segtotal;            /* total number of segments, this value is the
				 * number of segments of @segsize and should be
				 * chosen so that it matches buffer_time as
				 * close as possible. */
  /* out */
  gint     bytes_per_sample;    /* number of bytes of one sample */
  guint8   silence_sample[32];  /* bytes representing silence */

  /* ABI added 0.10.20 */
  gint     seglatency;          /* number of segments queued in the lower
				 * level device, defaults to segtotal. */
};

The structure containing the format specification of the ringbuffer.

GstRingBufferCallback ()

void                (*GstRingBufferCallback)            (GstRingBuffer *rbuf,
                                                         guint8 *data,
                                                         guint len,
                                                         gpointer user_data);

This function is set with gst_ring_buffer_set_callback() and is called to fill the memory at data with len bytes of samples.

enum GstRingBufferSegState

typedef enum {
  GST_SEGSTATE_INVALID,
  GST_SEGSTATE_EMPTY,
  GST_SEGSTATE_FILLED,
  GST_SEGSTATE_PARTIAL
} GstRingBufferSegState;

The state of a segment in the ringbuffer.

enum GstRingBufferState

typedef enum {
  GST_RING_BUFFER_STATE_STOPPED,
  GST_RING_BUFFER_STATE_PAUSED,
  GST_RING_BUFFER_STATE_STARTED
} GstRingBufferState;

The state of the ringbuffer.

enum GstBufferFormat

typedef enum {
  GST_UNKNOWN,

  GST_S8,
  GST_U8,

  GST_S16_LE,
  GST_S16_BE,
  GST_U16_LE,
  GST_U16_BE,

  GST_S24_LE,
  GST_S24_BE,
  GST_U24_LE,
  GST_U24_BE,

  GST_S32_LE,
  GST_S32_BE,
  GST_U32_LE,
  GST_U32_BE,

  GST_S24_3LE,
  GST_S24_3BE,
  GST_U24_3LE,
  GST_U24_3BE,
  GST_S20_3LE,
  GST_S20_3BE,
  GST_U20_3LE,
  GST_U20_3BE,
  GST_S18_3LE,
  GST_S18_3BE,
  GST_U18_3LE,
  GST_U18_3BE,

  GST_FLOAT32_LE,
  GST_FLOAT32_BE,

  GST_FLOAT64_LE,
  GST_FLOAT64_BE,

  GST_MU_LAW,
  GST_A_LAW,
  GST_IMA_ADPCM,
  GST_MPEG,
  GST_GSM,
  GST_IEC958,
  GST_AC3,
  GST_EAC3,
  GST_DTS,
  GST_MPEG2_AAC,
  GST_MPEG4_AAC,
} GstBufferFormat;

The detailed format of the samples in the ringbuffer.

enum GstBufferFormatType

typedef enum {
  GST_BUFTYPE_LINEAR,
  GST_BUFTYPE_FLOAT,
  GST_BUFTYPE_MU_LAW,
  GST_BUFTYPE_A_LAW,
  GST_BUFTYPE_IMA_ADPCM,
  GST_BUFTYPE_MPEG,
  GST_BUFTYPE_GSM,
  GST_BUFTYPE_IEC958,
  GST_BUFTYPE_AC3,
  GST_BUFTYPE_EAC3,
  GST_BUFTYPE_DTS,
  GST_BUFTYPE_MPEG2_AAC,
  GST_BUFTYPE_MPEG4_AAC,
} GstBufferFormatType;

The format of the samples in the ringbuffer.

GST_RING_BUFFER_BROADCAST()

#define GST_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_RING_BUFFER_GET_COND (buf)))

GST_RING_BUFFER_GET_COND()

#define GST_RING_BUFFER_GET_COND(buf) (((GstRingBuffer *)buf)->cond)

GST_RING_BUFFER_SIGNAL()

#define GST_RING_BUFFER_SIGNAL(buf)   (g_cond_signal (GST_RING_BUFFER_GET_COND (buf)))

GST_RING_BUFFER_WAIT()

#define GST_RING_BUFFER_WAIT(buf)     (g_cond_wait (GST_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))

gst_ring_buffer_set_callback ()

void                gst_ring_buffer_set_callback        (GstRingBuffer *buf,
                                                         GstRingBufferCallback cb,
                                                         gpointer user_data);

Sets the given callback function on the buffer. This function will be called every time a segment has been written to a device.

MT safe.

gst_ring_buffer_acquire ()

gboolean            gst_ring_buffer_acquire             (GstRingBuffer *buf,
                                                         GstRingBufferSpec *spec);

Allocate the resources for the ringbuffer. This function fills in the data pointer of the ring buffer with a valid GstBuffer to which samples can be written.

gst_ring_buffer_release ()

gboolean            gst_ring_buffer_release             (GstRingBuffer *buf);

Free the resources of the ringbuffer.

gst_ring_buffer_is_acquired ()

gboolean            gst_ring_buffer_is_acquired         (GstRingBuffer *buf);

Check if the ringbuffer is acquired and ready to use.

gst_ring_buffer_activate ()

gboolean            gst_ring_buffer_activate            (GstRingBuffer *buf,
                                                         gboolean active);

Activate buf to start or stop pulling data.

MT safe.

Since 0.10.22.

gst_ring_buffer_is_active ()

gboolean            gst_ring_buffer_is_active           (GstRingBuffer *buf);

Check if buf is activated.

MT safe.

Since 0.10.22.

gst_ring_buffer_start ()

gboolean            gst_ring_buffer_start               (GstRingBuffer *buf);

Start processing samples from the ringbuffer.

gst_ring_buffer_pause ()

gboolean            gst_ring_buffer_pause               (GstRingBuffer *buf);

Pause processing samples from the ringbuffer.

gst_ring_buffer_stop ()

gboolean            gst_ring_buffer_stop                (GstRingBuffer *buf);

Stop processing samples from the ringbuffer.

gst_ring_buffer_delay ()

guint               gst_ring_buffer_delay               (GstRingBuffer *buf);

Get the number of samples queued in the audio device. This is usually less than the segment size but can be bigger when the implementation uses another internal buffer between the audio device.

For playback ringbuffers this is the amount of samples transfered from the ringbuffer to the device but still not played.

For capture ringbuffers this is the amount of samples in the device that are not yet transfered to the ringbuffer.

gst_ring_buffer_samples_done ()

guint64             gst_ring_buffer_samples_done        (GstRingBuffer *buf);

Get the number of samples that were processed by the ringbuffer since it was last started. This does not include the number of samples not yet processed (see gst_ring_buffer_delay()).

gst_ring_buffer_set_sample ()

void                gst_ring_buffer_set_sample          (GstRingBuffer *buf,
                                                         guint64 sample);

Make sure that the next sample written to the device is accounted for as being the sample sample written to the device. This value will be used in reporting the current sample position of the ringbuffer.

This function will also clear the buffer with silence.

MT safe.

gst_ring_buffer_commit ()

guint               gst_ring_buffer_commit              (GstRingBuffer *buf,
                                                         guint64 sample,
                                                         guchar *data,
                                                         guint len);

Same as gst_ring_buffer_commit_full() but with a in_samples and out_samples equal to len, ignoring accum.

gst_ring_buffer_commit_full ()

guint               gst_ring_buffer_commit_full         (GstRingBuffer *buf,
                                                         guint64 *sample,
                                                         guchar *data,
                                                         gint in_samples,
                                                         gint out_samples,
                                                         gint *accum);

Commit in_samples samples pointed to by data to the ringbuffer buf.

in_samples and out_samples define the rate conversion to perform on the samples in data. For negative rates, out_samples must be negative and in_samples positive.

When out_samples is positive, the first sample will be written at position sample in the ringbuffer. When out_samples is negative, the last sample will be written to sample in reverse order.

out_samples does not need to be a multiple of the segment size of the ringbuffer although it is recommended for optimal performance.

accum will hold a temporary accumulator used in rate conversion and should be set to 0 when this function is first called. In case the commit operation is interrupted, one can resume the processing by passing the previously returned accum value back to this function.

MT safe.

Since 0.10.11.

gst_ring_buffer_convert ()

gboolean            gst_ring_buffer_convert             (GstRingBuffer *buf,
                                                         GstFormat src_fmt,
                                                         gint64 src_val,
                                                         GstFormat dest_fmt,
                                                         gint64 *dest_val);

Convert src_val in src_fmt to the equivalent value in dest_fmt. The result will be put in dest_val.

Since 0.10.22.

gst_ring_buffer_prepare_read ()

gboolean            gst_ring_buffer_prepare_read        (GstRingBuffer *buf,
                                                         gint *segment,
                                                         guint8 **readptr,
                                                         gint *len);

Returns a pointer to memory where the data from segment segment can be found. This function is mostly used by subclasses.

gst_ring_buffer_read ()

guint               gst_ring_buffer_read                (GstRingBuffer *buf,
                                                         guint64 sample,
                                                         guchar *data,
                                                         guint len);

Read len samples from the ringbuffer into the memory pointed to by data. The first sample should be read from position sample in the ringbuffer.

len should not be a multiple of the segment size of the ringbuffer although it is recommended.

gst_ring_buffer_clear ()

void                gst_ring_buffer_clear               (GstRingBuffer *buf,
                                                         gint segment);

Clear the given segment of the buffer with silence samples. This function is used by subclasses.

MT safe.

gst_ring_buffer_clear_all ()

void                gst_ring_buffer_clear_all           (GstRingBuffer *buf);

Fill the ringbuffer with silence.

MT safe.

gst_ring_buffer_advance ()

void                gst_ring_buffer_advance             (GstRingBuffer *buf,
                                                         guint advance);

Subclasses should call this function to notify the fact that advance segments are now processed by the device.

MT safe.

gst_ring_buffer_close_device ()

gboolean            gst_ring_buffer_close_device        (GstRingBuffer *buf);

Close the audio device associated with the ring buffer. The ring buffer should already have been released via gst_ring_buffer_release().

gst_ring_buffer_open_device ()

gboolean            gst_ring_buffer_open_device         (GstRingBuffer *buf);

Open the audio device associated with the ring buffer. Does not perform any setup on the device. You must open the device before acquiring the ring buffer.

gst_ring_buffer_device_is_open ()

gboolean            gst_ring_buffer_device_is_open      (GstRingBuffer *buf);

Checks the status of the device associated with the ring buffer.

gst_ring_buffer_may_start ()

void                gst_ring_buffer_may_start           (GstRingBuffer *buf,
                                                         gboolean allowed);

Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples.

MT safe.

Since 0.10.6

gst_ring_buffer_parse_caps ()

gboolean            gst_ring_buffer_parse_caps          (GstRingBufferSpec *spec,
                                                         GstCaps *caps);

Parse caps into spec.

gst_ring_buffer_set_flushing ()

void                gst_ring_buffer_set_flushing        (GstRingBuffer *buf,
                                                         gboolean flushing);

Set the ringbuffer to flushing mode or normal mode.

MT safe.