gstringbuffer

gstringbuffer — Base class for audio ringbuffer implementations

Synopsis


#include <gst/audio/gstringbuffer.h>


            GstRingBuffer;
            GstRingBufferSpec;
            GstRingBufferClass;
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_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);
gboolean    gst_ring_buffer_prepare_read    (GstRingBuffer *buf,
                                             gint *segment,
                                             guint8 **readptr,
                                             gint *len);
void        gst_ring_buffer_clear           (GstRingBuffer *buf,
                                             gint segment);
void        gst_ring_buffer_advance         (GstRingBuffer *buf,
                                             guint advance);

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

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;
  
  GstClockTime latency_time;    /* the required/actual latency time */
  GstClockTime buffer_time;     /* the required/actual time of the buffer */
  gint     segsize;             /* size of one buffer segement */
  gint     segtotal;            /* total number of segments */

  /* out */
  gint     bytes_per_sample;    /* number of bytes of one sample */
  guint8   silence_sample[32];  /* bytes representing silence */
} 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
GstClockTime latency_time; the latency in time units
GstClockTime buffer_time; the total buffer size in time units
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

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

The vmethods that subclasses can override to implement the ringbuffer.

GstObjectClass 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

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

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.

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);

Commit len samples pointed to by data to the ringbuffer buf. The first sample should be written at position sample in the ringbuffer.

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

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_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_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_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

See Also

gstbaseaudiosink