gstringbuffer

gstringbuffer — Base class for audio ringbuffer implementations

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GstObject
        ╰── GstRingBuffer

Includes

#include <gst/audio/gstringbuffer.h>

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)

Functions

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.

Parameters

rbuf

a GstRingBuffer

 

data

target to fill

 

len

amount to fill

 

user_data

user data

 

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

buf

the GstRingBuffer to flush

 

flushing

the new mode

 

Types and Values

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.

Members

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

 

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.

Members

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

 

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.

Members

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

 

enum GstRingBufferSegState

The state of a segment in the ringbuffer.

Members

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

The state of the ringbuffer.

Members

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

The detailed format of the samples in the ringbuffer.

Members

GST_UNKNOWN

unspecified

 

GST_S8

integer signed 8 bit

 

GST_U8

integer unsigned 8 bit

 

GST_S16_LE

integer signed 16 bit little endian

 

GST_S16_BE

integer signed 16 bit big endian

 

GST_U16_LE

integer unsigned 16 bit little endian

 

GST_U16_BE

integer unsigned 16 bit big endian

 

GST_S24_LE

integer signed 24 bit little endian

 

GST_S24_BE

integer signed 24 bit big endian

 

GST_U24_LE

integer unsigned 24 bit little endian

 

GST_U24_BE

integer unsigned 24 bit big endian

 

GST_S32_LE

integer signed 32 bit little endian

 

GST_S32_BE

integer signed 32 bit big endian

 

GST_U32_LE

integer unsigned 32 bit little endian

 

GST_U32_BE

integer unsigned 32 bit big endian

 

GST_S24_3LE

integer signed 24 bit little endian packed in 3 bytes

 

GST_S24_3BE

integer signed 24 bit big endian packed in 3 bytes

 

GST_U24_3LE

integer unsigned 24 bit little endian packed in 3 bytes

 

GST_U24_3BE

integer unsigned 24 bit big endian packed in 3 bytes

 

GST_S20_3LE

integer signed 20 bit little endian packed in 3 bytes

 

GST_S20_3BE

integer signed 20 bit big endian packed in 3 bytes

 

GST_U20_3LE

integer unsigned 20 bit little endian packed in 3 bytes

 

GST_U20_3BE

integer unsigned 20 bit big endian packed in 3 bytes

 

GST_S18_3LE

integer signed 18 bit little endian packed in 3 bytes

 

GST_S18_3BE

integer signed 18 bit big endian packed in 3 bytes

 

GST_U18_3LE

integer unsigned 18 bit little endian packed in 3 bytes

 

GST_U18_3BE

integer unsigned 18 bit big endian packed in 3 bytes

 

GST_FLOAT32_LE

floating 32 bit little endian

 

GST_FLOAT32_BE

floating 32 bit big endian

 

GST_FLOAT64_LE

floating 64 bit little endian

 

GST_FLOAT64_BE

floating 64 bit big endian

 

GST_MU_LAW

mu-law

 

GST_A_LAW

a-law

 

GST_IMA_ADPCM

ima adpcm

 

GST_MPEG

mpeg audio (but not aac)

 

GST_GSM

gsm

 

GST_IEC958

IEC958 frames

 

GST_AC3

ac3

 

GST_EAC3

eac3

 

GST_DTS

dts

 

GST_MPEG2_AAC

mpeg-2 aac

 

GST_MPEG4_AAC

mpeg-4 aac

 

enum GstBufferFormatType

The format of the samples in the ringbuffer.

Members

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 (but not AAC) 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_BUFTYPE_MPEG2_AAC

samples in MPEG-2 AAC format

 

GST_BUFTYPE_MPEG4_AAC

samples in MPEG-4 AAC format

 

See Also

GstBaseAudioSink, GstAudioSink