gstringbuffer

gstringbuffer — Base class for audio ringbuffer implementations

Synopsis


#include <gst/audio/gstringbuffer.h>


            GstRingBuffer;
            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.

Last reviewed on 2005-11-24 (0.9.6)

Details

GstRingBuffer

typedef struct {
  GCond                 *cond;
  gboolean               open;
  gboolean               acquired;
  GstBuffer             *data;
  GstRingBufferSpec      spec;
  GstRingBufferSegState *segstate;
  gint                   samples_per_seg;     /* number of samples per segment */
  guint8                *empty_seg;

  gint                   state;         /* state of the buffer */
  gint                   segdone;       /* number of segments processed since last start */
  gint                   segbase;       /* segment corresponding to segment 0 */
  gint                   waiting;       /* when waiting for a segment to be freed */
} GstRingBuffer;


GstRingBufferClass

typedef struct {
  GstObjectClass parent_class;

  /* just open the device, don't set any params or allocate anything */
  gboolean     (*open_device)  (GstRingBuffer *buf);
  /* allocate the resources for the ringbuffer using the given specs */
  gboolean     (*acquire)      (GstRingBuffer *buf, GstRingBufferSpec *spec);
  /* free resources of the ringbuffer */
  gboolean     (*release)      (GstRingBuffer *buf);
  /* close the device */
  gboolean     (*close_device) (GstRingBuffer *buf);

  /* playback control */
  gboolean     (*start)        (GstRingBuffer *buf);
  gboolean     (*pause)        (GstRingBuffer *buf);
  gboolean     (*resume)       (GstRingBuffer *buf);
  gboolean     (*stop)         (GstRingBuffer *buf);

  /* number of samples queued in device */
  guint        (*delay)        (GstRingBuffer *buf);
} GstRingBufferClass;


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 not needs 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 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