# Gst::RingBuffer Class Reference
[gstreamermm Base Classes]

A base class for audio ringbuffer implementations. More...

Inherits Gst::Object.

Collaboration diagram for Gst::RingBuffer:
[legend]

List of all members.

## Public Types

typedef sigc::slot< void, const Glib::ArrayHandle < guint8 >&, guint > | SlotFill
| For example, bool on_fill(const Glib::RefPtr<Gst::RingBuffer>& rbuf, const std::vector<guint8>& data, guint len);.

## Public Member Functions

virtual | ~RingBuffer ()
GstRingBuffer* | gobj ()
| Provides access to the underlying C GObject.
const GstRingBuffer* | gobj () const
| Provides access to the underlying C GObject.
GstRingBuffer* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void | set_fill_slot (const SlotFill& slot)
| Sets the given fill slot on the buffer.
bool | acquire (Gst::RingBufferSpec& spec)
| Allocate the resources for the ringbuffer.
bool | release ()
| Free the resources of the ringbuffer.
bool | is_acquired () const
| Check if the ringbuffer is acquired and ready to use.
bool | activate (bool active)
| Activate buf to start or stop pulling data.
bool | is_active () const
| Check if buf is activated.
bool | start ()
| Start processing samples from the ringbuffer.
bool | pause ()
| Pause processing samples from the ringbuffer.
bool | stop ()
| Stop processing samples from the ringbuffer.
guint | get_delay () const
| Get the number of samples queued in the audio device.
guint64 | get_samples_done () const
| Get the number of samples that were processed by the ringbuffer since it was last started.
void | set_sample (guint64 sample)
| Make sure that the next sample written to the device is accounted for as being the sample sample written to the device.
guint | commit (guint64 sample, const Glib::ArrayHandle< guchar >& data, guint len)
| Same as commit_full() but with a in_samples and out_samples equal to len, ignoring accum.
guint | commit (guint64& sample, const Glib::ArrayHandle< guchar >& data, int in_samples, int out_samples, int& accum)
| Commit in_samples samples pointed to by data to the ringbuffer buf.
bool | convert (Gst::Format src_fmt, gint64 src_val, Gst::Format dest_fmt, gint64& dest_val) const
| Convert src_val in src_fmt to the equivalent value in dest_fmt.
bool | prepare_read (int& segment, std::vector< guint8 >& readptr, int& len)
| Returns: `false` if the buffer is not started.
guint | read (guint64 sample, const Glib::ArrayHandle< guchar >& data, guint len)
| Read len samples from the ringbuffer into the memory pointed to by data.
void | clear (int segment)
| Clear the given segment of the buffer with silence samples.
void | clear_all ()
| Fill the ringbuffer with silence.
void | advance (guint advance)
| Subclasses should call this function to notify the fact that advance segments are now processed by the device.
bool | close_device ()
| Close the audio device associated with the ring buffer.
bool | open_device ()
| Open the audio device associated with the ring buffer.
bool | device_is_open () const
| Checks the status of the device associated with the ring buffer.
void | set_may_start (bool allowed)
| Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples.
void | set_flushing (bool flushing)
| Set the ringbuffer to flushing mode or normal mode.
virtual bool | open_device_vfunc ()
| Virtual function to open the device.
virtual bool | acquire_vfunc (Gst::RingBufferSpec& spec)
| Virtual function to allocate the resources for the ring buffer using the given spec.
virtual bool | release_vfunc ()
| Virtual function to free resources of the ring buffer.
virtual bool | close_device_vfunc ()
| Virtual function to close the device.
virtual bool | start_vfunc ()
| Virtual function to start processing of samples.
virtual bool | pause_vfunc ()
| Virtual function to pause processing of samples.
virtual bool | resume_vfunc ()
| Virtual function to resume processing of samples after pause.
virtual bool | stop_vfunc ()
| Virtual function to stop processing of samples.
virtual guint | delay_vfunc ()
| Virtual function to get number of samples queued in device.
virtual bool | activate_vfunc (bool active)
| Virtual function to activate the thread that starts pulling and monitoring the consumed segments in the device.
virtual guint | commit_vfunc (guint64& sample, const Glib::ArrayHandle< guchar >& data, int in_samples, int out_samples, int& accum)
| Virtual function to write samples into the ring buffer.
virtual void | clear_all_vfunc ()
| Virtual function to clear the entire ringbuffer Since 0.10.24.

## Static Public Member Functions

static bool | parse_caps (Gst::RingBufferSpec&, const Glib::RefPtr< Gst::Caps >& caps)
| Parse caps into spec.

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gst::RingBuffer > | wrap (GstRingBuffer* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

A base class for audio ringbuffer implementations.

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

## Member Typedef Documentation

typedef sigc::slot<void, const Glib::ArrayHandle<guint8>&, guint> Gst::RingBuffer::SlotFill

For example, bool on_fill(const Glib::RefPtr<Gst::RingBuffer>& rbuf, const std::vector<guint8>& data, guint len);.

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

## Constructor & Destructor Documentation

virtual Gst::RingBuffer::~RingBuffer | ( |  | ) | `[virtual]`

## Member Function Documentation

bool Gst::RingBuffer::acquire | ( | Gst::RingBufferSpec& | spec | ) |

Allocate the resources for the ringbuffer.

This function fills in the data pointer of the ring buffer with a valid Gst::Buffer to which samples can be written.

Parameters:

  | spec | The specs of the buffer.

Returns:
  `true` if the device could be acquired, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::acquire_vfunc | ( | Gst::RingBufferSpec& | spec | ) | `[virtual]`

Virtual function to allocate the resources for the ring buffer using the given spec.

bool Gst::RingBuffer::activate | ( | bool | active | ) |

Activate buf to start or stop pulling data.

MT safe.

Parameters:

  | active | The new mode.

Returns:
  `true` if the device could be activated in the requested mode, `false` on error.

Since gstreamermm 0.10:
  .22.

virtual bool Gst::RingBuffer::activate_vfunc | ( | bool | active | ) | `[virtual]`

Virtual function to activate the thread that starts pulling and monitoring the consumed segments in the device.

Since 0.10.22.

void Gst::RingBuffer::advance | ( | guint | advance | ) |

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

MT safe.

Parameters:

  | advance | The number of segments written.

void Gst::RingBuffer::clear | ( | int | segment | ) |

Clear the given segment of the buffer with silence samples.

This function is used by subclasses.

MT safe.

Parameters:

  | segment | The segment to clear.

void Gst::RingBuffer::clear_all | ( |  | ) |

Fill the ringbuffer with silence.

MT safe.

virtual void Gst::RingBuffer::clear_all_vfunc | ( |  | ) | `[virtual]`

Virtual function to clear the entire ringbuffer Since 0.10.24.

bool Gst::RingBuffer::close_device | ( |  | ) |

Close the audio device associated with the ring buffer.

The ring buffer should already have been released via release().

Returns:
  `true` if the device could be closed, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::close_device_vfunc | ( |  | ) | `[virtual]`

Virtual function to close the device.

guint Gst::RingBuffer::commit | ( | guint64 & | sample,
|  | const Glib::ArrayHandle< guchar > & | data,
|  | int | in_samples,
|  | int | out_samples,
|  | int & | 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.

Parameters:

  | 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 gstreamermm 0.10:
  .11.

guint Gst::RingBuffer::commit | ( | guint64 | sample,
|  | const Glib::ArrayHandle< guchar > & | data,
|  | guint | len |
| ) |  |  |

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

Parameters:

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

virtual guint Gst::RingBuffer::commit_vfunc | ( | guint64 & | sample,
|  | const Glib::ArrayHandle< guchar > & | data,
|  | int | in_samples,
|  | int | out_samples,
|  | int & | accum |
| ) |  |  | `[virtual]`

Virtual function to write samples into the ring buffer.

bool Gst::RingBuffer::convert | ( | Gst::Format | src_fmt,
|  | gint64 | src_val,
|  | Gst::Format | dest_fmt,
|  | gint64 & | dest_val |
| ) |  |  | const

Convert src_val in src_fmt to the equivalent value in dest_fmt.

The result will be put in dest_val.

Parameters:

  | 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 gstreamermm 0.10:
  .22.

virtual guint Gst::RingBuffer::delay_vfunc | ( |  | ) | `[virtual]`

Virtual function to get number of samples queued in device.

bool Gst::RingBuffer::device_is_open | ( |  | ) | const

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

Returns:
  `true` if the device was open, `false` if it was closed.

MT safe.

guint Gst::RingBuffer::get_delay | ( |  | ) | const

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.

Returns:
  The number of samples queued in the audio device.

MT safe.

guint64 Gst::RingBuffer::get_samples_done | ( |  | ) | const

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

Returns:
  The number of samples processed by the ringbuffer.

MT safe.

const GstRingBuffer* Gst::RingBuffer::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Gst::Object.

GstRingBuffer* Gst::RingBuffer::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Gst::Object.

GstRingBuffer* Gst::RingBuffer::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Gst::Object.

bool Gst::RingBuffer::is_acquired | ( |  | ) | const

Check if the ringbuffer is acquired and ready to use.

Returns:
  `true` if the ringbuffer is acquired, `false` on error.

MT safe.

bool Gst::RingBuffer::is_active | ( |  | ) | const

Check if buf is activated.

MT safe.

Returns:
  `true` if the device is active.

Since gstreamermm 0.10:
  .22.

bool Gst::RingBuffer::open_device | ( |  | ) |

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.

Returns:
  `true` if the device could be opened, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::open_device_vfunc | ( |  | ) | `[virtual]`

Virtual function to open the device.

Don't set any params or allocate anything.

static bool Gst::RingBuffer::parse_caps | ( | Gst::RingBufferSpec& | ,
|  | const Glib::RefPtr< Gst::Caps >& | caps |
| ) |  |  | `[static]`

Parse caps into spec.

Parameters:

  | spec | A spec.
  | caps | A Gst::Caps.

Returns:
  `true` if the caps could be parsed.

bool Gst::RingBuffer::pause | ( |  | ) |

Pause processing samples from the ringbuffer.

Returns:
  `true` if the device could be paused, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::pause_vfunc | ( |  | ) | `[virtual]`

Virtual function to pause processing of samples.

bool Gst::RingBuffer::prepare_read | ( | int & | segment,
|  | std::vector< guint8 > & | readptr,
|  | int & | len |
| ) |  |  |

Returns: `false` if the buffer is not started.

Parameters:

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

guint Gst::RingBuffer::read | ( | guint64 | sample,
|  | const Glib::ArrayHandle< 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:

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

bool Gst::RingBuffer::release | ( |  | ) |

Free the resources of the ringbuffer.

Returns:
  `true` if the device could be released, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::release_vfunc | ( |  | ) | `[virtual]`

Virtual function to free resources of the ring buffer.

virtual bool Gst::RingBuffer::resume_vfunc | ( |  | ) | `[virtual]`

Virtual function to resume processing of samples after pause.

void Gst::RingBuffer::set_fill_slot | ( | const SlotFill & | slot | ) |

Sets the given fill slot on the buffer.

The slot will be called every time a segment has been written to a device.

MT safe.

Parameters:

  | slot | The fill slot to set.

void Gst::RingBuffer::set_flushing | ( | bool | flushing | ) |

Set the ringbuffer to flushing mode or normal mode.

MT safe.

Parameters:

  | flushing | The new mode.

void Gst::RingBuffer::set_may_start | ( | bool | allowed | ) |

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

MT safe.

Since gstreamermm 0.10:
  .6

Parameters:

  | allowed | The new value.

void Gst::RingBuffer::set_sample | ( | 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:

  | sample | The sample number to set.

bool Gst::RingBuffer::start | ( |  | ) |

Start processing samples from the ringbuffer.

Returns:
  `true` if the device could be started, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::start_vfunc | ( |  | ) | `[virtual]`

Virtual function to start processing of samples.

bool Gst::RingBuffer::stop | ( |  | ) |

Stop processing samples from the ringbuffer.

Returns:
  `true` if the device could be stopped, `false` on error.

MT safe.

virtual bool Gst::RingBuffer::stop_vfunc | ( |  | ) | `[virtual]`

Virtual function to stop processing of samples.

## Friends And Related Function Documentation

Glib::RefPtr< Gst::RingBuffer > wrap | ( | GstRingBuffer * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- gstreamermm/ringbuffer.h