## gstringbuffer

gstringbuffer — Base class for audio ringbuffer implementations

## Synopsis

    #include <gst/audio/gstringbuffer.h>

                        GstRingBuffer;
                        GstRingBufferClass;
                        GstRingBufferSpec;
    void                (*GstRingBufferCallback)            (GstRingBuffer *rbuf,
                                                             guint8 *data,
                                                             guint len,
                                                             gpointer user_data);
    enum                GstRingBufferSegState;
    enum                GstRingBufferState;
    enum                GstBufferFormat;
    enum                GstBufferFormatType;
    #define             GST_RING_BUFFER_BROADCAST           (buf)
    #define             GST_RING_BUFFER_GET_COND            (buf)
    #define             GST_RING_BUFFER_SIGNAL              (buf)
    #define             GST_RING_BUFFER_WAIT                (buf)
    void                gst_ring_buffer_set_callback        (GstRingBuffer *buf,
                                                             GstRingBufferCallback cb,
                                                             gpointer user_data);
    gboolean            gst_ring_buffer_acquire             (GstRingBuffer *buf,
                                                             GstRingBufferSpec *spec);
    gboolean            gst_ring_buffer_release             (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_is_acquired         (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_activate            (GstRingBuffer *buf,
                                                             gboolean active);
    gboolean            gst_ring_buffer_is_active           (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_start               (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_pause               (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_stop                (GstRingBuffer *buf);
    guint               gst_ring_buffer_delay               (GstRingBuffer *buf);
    guint64             gst_ring_buffer_samples_done        (GstRingBuffer *buf);
    void                gst_ring_buffer_set_sample          (GstRingBuffer *buf,
                                                             guint64 sample);
    guint               gst_ring_buffer_commit              (GstRingBuffer *buf,
                                                             guint64 sample,
                                                             guchar *data,
                                                             guint len);
    guint               gst_ring_buffer_commit_full         (GstRingBuffer *buf,
                                                             guint64 *sample,
                                                             guchar *data,
                                                             gint in_samples,
                                                             gint out_samples,
                                                             gint *accum);
    gboolean            gst_ring_buffer_convert             (GstRingBuffer *buf,
                                                             GstFormat src_fmt,
                                                             gint64 src_val,
                                                             GstFormat dest_fmt,
                                                             gint64 *dest_val);
    gboolean            gst_ring_buffer_prepare_read        (GstRingBuffer *buf,
                                                             gint *segment,
                                                             guint8 **readptr,
                                                             gint *len);
    guint               gst_ring_buffer_read                (GstRingBuffer *buf,
                                                             guint64 sample,
                                                             guchar *data,
                                                             guint len);
    void                gst_ring_buffer_clear               (GstRingBuffer *buf,
                                                             gint segment);
    void                gst_ring_buffer_clear_all           (GstRingBuffer *buf);
    void                gst_ring_buffer_advance             (GstRingBuffer *buf,
                                                             guint advance);
    gboolean            gst_ring_buffer_close_device        (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_open_device         (GstRingBuffer *buf);
    gboolean            gst_ring_buffer_device_is_open      (GstRingBuffer *buf);
    void                gst_ring_buffer_may_start           (GstRingBuffer *buf,
                                                             gboolean allowed);
    gboolean            gst_ring_buffer_parse_caps          (GstRingBufferSpec *spec,
                                                             GstCaps *caps);
    void                gst_ring_buffer_set_flushing        (GstRingBuffer *buf,
                                                             gboolean flushing);

## Object Hierarchy

      GObject
       +----GstObject
             +----GstRingBuffer

## Description

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.

Last reviewed on 2006-02-02 (0.10.4)

## Details

### GstRingBuffer

    typedef struct {
      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;
    } GstRingBuffer;

The ringbuffer base class structure.

GCond *`cond`; | used to signal start/stop/pause/resume actions
gboolean `open`; | boolean indicating that the ringbuffer is open
gboolean `acquired`; | boolean indicating that the ringbuffer is acquired
GstBuffer *`data`; | data in the ringbuffer
GstRingBufferSpec `spec`; | format and layout of the ringbuffer data
GstRingBufferSegState *`segstate`; | status of each segment in the ringbuffer (unused)
gint `samples_per_seg`; | number of samples in one segment
guint8 *`empty_seg`; | pointer to memory holding one segment of silence samples
gint `state`; | state of the buffer
gint `segdone`; | readpointer in the ringbuffer
gint `segbase`; | segment corresponding to segment 0 (unused)
gint `waiting`; | is a reader or writer waiting for a free segment

### GstRingBufferClass

    typedef struct {
      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);
    } GstRingBufferClass;

The vmethods that subclasses can override to implement the ringbuffer.

GstObjectClass `parent_class`; | parent class
`open_device` () | open the device, don't set any params or allocate anything
`acquire` () | allocate the resources for the ringbuffer using the given spec
`release` () | free resources of the ringbuffer
`close_device` () | close the device
`start` () | start processing of samples
`pause` () | pause processing of samples
`resume` () | resume processing of samples after pause
`stop` () | stop processing of samples
`delay` () | get number of samples queued in device
`activate` () | activate the thread that starts pulling and monitoring the consumed segments in the device. Since 0.10.22
`commit` () | write samples into the ringbuffer
`clear_all` () | clear the entire ringbuffer Since 0.10.24

### GstRingBufferSpec

    typedef struct {
      /* 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. */
    } GstRingBufferSpec;

The structure containing the format specification of the ringbuffer.

GstCaps *`caps`; | The caps that generated the Spec.
GstBufferFormatType `type`; | the sample type
GstBufferFormat `format`; | the sample format
gboolean `sign`; | the sample sign
gboolean `bigend`; | the endianness of the samples
gint `width`; | the width of the samples
gint `depth`; | th depth of the samples
gint `rate`; | the samplerate
gint `channels`; | the number of channels
guint64 `latency_time`; | the latency in microseconds
guint64 `buffer_time`; | the total buffer size in microseconds
gint `segsize`; | the size of one segment in bytes
gint `segtotal`; | the total number of segments
gint `bytes_per_sample`; | number of bytes in one sample
guint8 `silence_sample`[32]; | bytes representing one sample of silence
gint `seglatency`; | number of segments queued in the lower level device, defaults to segtotal

### 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.

`rbuf` : | a GstRingBuffer
`data` : | target to fill
`len` : | amount to fill
`user_data` : | user data

### 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.

`GST_SEGSTATE_INVALID` | The content of the segment is invalid
`GST_SEGSTATE_EMPTY` | The segment is empty
`GST_SEGSTATE_FILLED` | The segment contains valid data
`GST_SEGSTATE_PARTIAL` | The segment partially contains valid data

### 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.

`GST_RING_BUFFER_STATE_STOPPED` | The ringbuffer is stopped
`GST_RING_BUFFER_STATE_PAUSED` | The ringbuffer is paused
`GST_RING_BUFFER_STATE_STARTED` | The ringbuffer is started

### 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
    } GstBufferFormat;

### 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
    } GstBufferFormatType;

The format of the samples in the ringbuffer.

`GST_BUFTYPE_LINEAR` | samples in linear PCM
`GST_BUFTYPE_FLOAT` | samples in float
`GST_BUFTYPE_MU_LAW` | samples in mulaw
`GST_BUFTYPE_A_LAW` | samples in alaw
`GST_BUFTYPE_IMA_ADPCM` | samples in ima adpcm
`GST_BUFTYPE_MPEG` | samples in mpeg audio format
`GST_BUFTYPE_GSM` | samples in gsm format
`GST_BUFTYPE_IEC958` | samples in IEC958 frames (e.g. AC3)
`GST_BUFTYPE_AC3` | samples in AC3 format
`GST_BUFTYPE_EAC3` | samples in EAC3 format
`GST_BUFTYPE_DTS` | samples in DTS format

### 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.

`buf` : | the GstRingBuffer to set the callback on
`cb` : | the callback to set
`user_data` : | user data passed to the callback

### 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.

`buf` : | the GstRingBuffer to acquire
`spec` : | the specs of the buffer
Returns : | TRUE if the device could be acquired, FALSE on error. MT safe.

### gst_ring_buffer_release ()

    gboolean            gst_ring_buffer_release             (GstRingBuffer *buf);

Free the resources of the ringbuffer.

`buf` : | the GstRingBuffer to release
Returns : | TRUE if the device could be released, FALSE on error. MT safe.

### gst_ring_buffer_is_acquired ()

    gboolean            gst_ring_buffer_is_acquired         (GstRingBuffer *buf);

Check if the ringbuffer is acquired and ready to use.

`buf` : | the GstRingBuffer to check
Returns : | TRUE if the ringbuffer is acquired, FALSE on error. MT safe.

### gst_ring_buffer_activate ()

    gboolean            gst_ring_buffer_activate            (GstRingBuffer *buf,
                                                             gboolean active);

Activate `buf` to start or stop pulling data.

MT safe.

`buf` : | the GstRingBuffer to activate
`active` : | the new mode
Returns : | TRUE if the device could be activated in the requested mode, FALSE on error.

Since 0.10.22.

### gst_ring_buffer_is_active ()

    gboolean            gst_ring_buffer_is_active           (GstRingBuffer *buf);

Check if `buf` is activated.

MT safe.

`buf` : | the GstRingBuffer
Returns : | TRUE if the device is active.

Since 0.10.22.

### gst_ring_buffer_start ()

    gboolean            gst_ring_buffer_start               (GstRingBuffer *buf);

Start processing samples from the ringbuffer.

`buf` : | the GstRingBuffer to start
Returns : | TRUE if the device could be started, FALSE on error. MT safe.

### gst_ring_buffer_pause ()

    gboolean            gst_ring_buffer_pause               (GstRingBuffer *buf);

Pause processing samples from the ringbuffer.

`buf` : | the GstRingBuffer to pause
Returns : | TRUE if the device could be paused, FALSE on error. MT safe.

### gst_ring_buffer_stop ()

    gboolean            gst_ring_buffer_stop                (GstRingBuffer *buf);

Stop processing samples from the ringbuffer.

`buf` : | the GstRingBuffer to stop
Returns : | TRUE if the device could be stopped, FALSE on error. MT safe.

### 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.

`buf` : | the GstRingBuffer to query
Returns : | The number of samples queued in the audio device. MT safe.

### 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()`).

`buf` : | the GstRingBuffer to query
Returns : | The number of samples processed by the ringbuffer. MT safe.

### 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.

`buf` : | the GstRingBuffer to use
`sample` : | the sample number to set

### 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.

`buf` : | the GstRingBuffer to commit
`sample` : | the sample position of the data
`data` : | the data to commit
`len` : | the number of samples in the data to commit
Returns : | The number of samples written to the ringbuffer or -1 on error. MT safe.

### 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 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.

`buf` : | the GstRingBuffer to commit
`sample` : | the sample position of the data
`data` : | the data to commit
`in_samples` : | the number of samples in the data to commit
`out_samples` : | the number of samples to write to the ringbuffer
`accum` : | accumulator for rate conversion.
Returns : | The number of samples written to the ringbuffer or -1 on error. The number of samples written can be less than `out_samples` when `buf` was interrupted with a flush or stop.

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`.

`buf` : | the GstRingBuffer
`src_fmt` : | the source format
`src_val` : | the source value
`dest_fmt` : | the destination format
`dest_val` : | a location to store the converted value
Returns : | TRUE if the conversion succeeded.

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.

`buf` : | the GstRingBuffer to read from
`segment` : | the segment to read
`readptr` : | the pointer to the memory where samples can be read
`len` : | the number of bytes to read
Returns : | FALSE if the buffer is not started. MT safe.

### 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.

`buf` : | the GstRingBuffer to read from
`sample` : | the sample position of the data
`data` : | where the data should be read
`len` : | the number of samples in data to read
Returns : | The number of samples read from the ringbuffer or -1 on error. MT safe.

### 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.

`buf` : | the GstRingBuffer to clear
`segment` : | the segment to clear

### gst_ring_buffer_clear_all ()

    void                gst_ring_buffer_clear_all           (GstRingBuffer *buf);

Fill the ringbuffer with silence.

MT safe.

`buf` : | the GstRingBuffer to clear

### 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.

`buf` : | the GstRingBuffer to advance
`advance` : | the number of segments written

### 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()`.

`buf` : | the GstRingBuffer
Returns : | TRUE if the device could be closed, FALSE on error. MT safe.

### 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.

`buf` : | the GstRingBuffer
Returns : | TRUE if the device could be opened, FALSE on error. MT safe.

### 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.

`buf` : | the GstRingBuffer
Returns : | TRUE if the device was open, FALSE if it was closed. MT safe.

### 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.

`buf` : | the GstRingBuffer
`allowed` : | the new value

Since 0.10.6

### gst_ring_buffer_parse_caps ()

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

Parse `caps` into `spec`.

`spec` : | a spec
`caps` : | a GstCaps
Returns : | TRUE if the caps could be parsed.

### 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.

`buf` : | the GstRingBuffer to flush
`flushing` : | the new mode

## See Also

GstBaseAudioSink, GstAudioSink