gstreamermm: Gst::AudioRingBuffer Class Reference

gstreamermm 1.10.0

Public Types | Public Member Functions | Static Public Member Functions | Related Functions | List of all members
Gst::AudioRingBuffer Class Reference
gstreamermm Base Classes

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

`#include <gstreamermm/audioringbuffer.h>`

Inheritance diagram for Gst::AudioRingBuffer:
[legend]

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

## Public Member Functions
| AudioRingBuffer (AudioRingBuffer&& src) noexcept
AudioRingBuffer& | operator= (AudioRingBuffer&& src) noexcept
| ~AudioRingBuffer () noexcept override
GstAudioRingBuffer* | gobj ()
| Provides access to the underlying C GObject. More...
const GstAudioRingBuffer* | gobj () const
| Provides access to the underlying C GObject. More...
GstAudioRingBuffer* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
void | set_fill_slot (const SlotFill& slot)
| Sets the given fill slot on the buffer. More...
bool | acquire (Gst::AudioRingBufferSpec& spec)
| Allocate the resources for the ringbuffer. More...
bool | release ()
| Free the resources of the ringbuffer. More...
bool | is_acquired () const
| Check if the ringbuffer is acquired and ready to use. More...
bool | activate (bool active)
| Activate buf to start or stop pulling data. More...
bool | is_active () const
| Check if buf is activated. More...
bool | start ()
| Start processing samples from the ringbuffer. More...
bool | pause ()
| Pause processing samples from the ringbuffer. More...
bool | stop ()
| Stop processing samples from the ringbuffer. More...
guint | get_delay () const
| Get the number of samples queued in the audio device. More...
guint64 | get_samples_done () const
| Get the number of samples that were processed by the ringbuffer since it was last started. More...
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. More...
void | set_channel_position (const Gst::AudioChannelPosition& position)
| Tell the ringbuffer about the device's channel positions. More...
gboolean | is_flushing ()
| Check if buf is flushing. More...
void | set_timestamp (gint readseg, ClockTime timestamp)
guint | commit (guint64& sample, const std::vector< guint8 >& data, int in_samples, int out_samples, int& accum)
| Commit in_samples samples pointed to by data to the ringbuffer buf. More...
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. More...
bool | prepare_read (int& segment, std::vector< guint8 >& readptr, int& len)
| Returns a pointer to memory where the data from segment segment can be found. More...
guint | read (guint64 sample, const std::vector< guint8 >& data, guint len, Gst::ClockTime& timestamp)
| Read len samples from the ringbuffer into the memory pointed to by data. More...
void | clear (int segment)
| Clear the given segment of the buffer with silence samples. More...
void | clear_all ()
| Fill the ringbuffer with silence. More...
void | advance (guint advance)
| Subclasses should call this function to notify the fact that advance segments are now processed by the device. More...
bool | close_device ()
| Close the audio device associated with the ring buffer. More...
bool | open_device ()
| Open the audio device associated with the ring buffer. More...
bool | device_is_open () const
| Checks the status of the device associated with the ring buffer. More...
void | set_may_start (bool allowed)
| Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples. More...
void | set_flushing (bool flushing)
| Set the ringbuffer to flushing mode or normal mode. More...
virtual bool | open_device_vfunc ()
| Virtual function to open the device. More...
virtual bool | acquire_vfunc (Gst::AudioRingBufferSpec& spec)
| Virtual function to allocate the resources for the ring buffer using the given spec. More...
virtual bool | release_vfunc ()
| Virtual function to free resources of the ring buffer. More...
virtual bool | close_device_vfunc ()
| Virtual function to close the device. More...
virtual bool | start_vfunc ()
| Virtual function to start processing of samples. More...
virtual bool | pause_vfunc ()
| Virtual function to pause processing of samples. More...
virtual bool | resume_vfunc ()
| Virtual function to resume processing of samples after pause. More...
virtual bool | stop_vfunc ()
| Virtual function to stop processing of samples. More...
virtual guint | delay_vfunc ()
| Virtual function to get number of samples queued in device. More...
virtual bool | activate_vfunc (bool active)
| Virtual function to activate the thread that starts pulling and monitoring the consumed segments in the device. More...
virtual guint | commit_vfunc (guint64& sample, const std::vector< guint8 >& data, int in_samples, int out_samples, int& accum)
| Virtual function to write samples into the ring buffer. More...
virtual void | clear_all_vfunc ()
| Virtual function to clear the entire audioringbuffer Since 0.10.24. More...
Public Member Functions inherited from Gst::Object
| Object (Object&& src) noexcept
Object& | operator= (Object&& src) noexcept
| ~Object () noexcept override
GstObject* | gobj ()
| Provides access to the underlying C GObject. More...
const GstObject* | gobj () const
| Provides access to the underlying C GObject. More...
GstObject* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
bool | is_element () const
bool | is_element_factory () const
bool | is_pad () const
bool | is_pad_template () const
bool | is_bin () const
guint32 | get_flags () const
| Returns the entire set of flags for the object. More...
bool | set_name (const Glib::ustring& name)
| Sets the name of object, or gives object a guaranteed unique name (if name is `nullptr`). More...
Glib::ustring | get_name () const
| Returns a copy of the name of object. More...
bool | set_parent (const Glib::RefPtr< Gst::Object >& parent)
| Sets the parent of object to parent. More...
Glib::RefPtr< Gst::Object > | get_parent ()
| Returns the parent of object. More...
Glib::RefPtr< const Gst::Object > | get_parent () const
| Returns the parent of object. More...
void | unparent ()
| Clear the parent of object, removing the associated reference. More...
void | set_control_rate (Gst::ClockTime control_rate)
| Change the control-rate for this object. More...
Gst::ClockTime | get_control_rate () const
| Obtain the control-rate for this object. More...
Gst::ClockTime | suggest_next_sync () const
| Returns a suggestion for timestamps where buffers should be split to get best controller results. More...
bool | sync_values (Gst::ClockTime timestamp)
| Sets the properties of the object, according to the Gst::ControlSources that (maybe) handle them and for the given timestamp. More...
void | set_control_bindings_disabled (bool disabled)
| This function is used to disable all controlled properties of the object for some time, i.e. sync_values() will do nothing. More...
bool | has_asctive_control_bindings () const
| Check if the object has an active controlled properties. More...
bool | has_ancestor (const Glib::RefPtr< const Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
bool | has_as_ancestor (const Glib::RefPtr< Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
bool | has_as_parent (const Glib::RefPtr< Gst::Object >& parent) const
| Check if parent is the parent of object. More...
Glib::ustring | get_path_string ()
| Generates a string describing the path of object in the object hierarchy. More...
Glib::PropertyProxy< Glib::ustring > | property_name ()
| The name of the object. More...
Glib::PropertyProxy_ReadOnly< Glib::ustring > | property_name () const
| The name of the object. More...
Glib::PropertyProxy< Glib::RefPtr< Gst::Object > > | property_parent ()
| The parent of the object. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gst::Object > > | property_parent () const
| The parent of the object. More...
Glib::SignalProxy< void, const Glib::RefPtr< Gst::Object >&, GParamSpec*> | signal_deep_notify ()
int | get_refcount () const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static bool | parse_caps (Gst::AudioRingBufferSpec& p1, const Glib::RefPtr< Gst::Caps >& caps)
| Parse caps into p1. More...
Static Public Member Functions inherited from Gst::Object
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static bool | check_uniqueness (const Glib::ListHandle< const Gst::Object >& list, const Glib::ustring& name)
| Checks to see if there is any object named name in list. More...

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gst::AudioRingBuffer > | wrap (GstAudioRingBuffer* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...
Related Functions inherited from Gst::Object
Glib::RefPtr< Gst::Object > | wrap (GstObject* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Protected Member Functions inherited from Gst::Object
virtual void | on_deep_notify (const Glib::RefPtr< Gst::Object >& prop_object, GParamSpec* prop)
| This is a default handler for the signal signal_deep_notify(). More...

## Detailed Description

A base class for audio audioringbuffer implementations.

This object is the base class for audio ringbuffers used by the base audio source and sink classes.

The audioringbuffer 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 audioringbuffer as well as a pure software implementations.

Last reviewed on 2016-04-23 (1.8.0).

## Member Typedef Documentation

## ◆ SlotFill

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

For example, bool on_fill(const Glib::RefPtr<Gst::AudioRingBuffer>& 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

## ◆ AudioRingBuffer()

Gst::AudioRingBuffer::AudioRingBuffer | ( | AudioRingBuffer&& | src | ) |
| noexcept

## ◆ ~AudioRingBuffer()

Gst::AudioRingBuffer::~AudioRingBuffer | ( |  | ) |
| overridenoexcept

## Member Function Documentation

## ◆ acquire()

bool Gst::AudioRingBuffer::acquire | ( | Gst::AudioRingBufferSpec& | 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.

## ◆ acquire_vfunc()

virtual bool Gst::AudioRingBuffer::acquire_vfunc | ( | Gst::AudioRingBufferSpec& | spec | ) |
| virtual

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

## ◆ activate()

bool Gst::AudioRingBuffer::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.

## ◆ activate_vfunc()

virtual bool Gst::AudioRingBuffer::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.

## ◆ advance()

void Gst::AudioRingBuffer::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.

## ◆ clear()

void Gst::AudioRingBuffer::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.

## ◆ clear_all()

void Gst::AudioRingBuffer::clear_all | ( |  | ) |

Fill the ringbuffer with silence.

MT safe.

## ◆ clear_all_vfunc()

virtual void Gst::AudioRingBuffer::clear_all_vfunc | ( |  | ) |
| virtual

Virtual function to clear the entire audioringbuffer Since 0.10.24.

## ◆ close_device()

bool Gst::AudioRingBuffer::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.

## ◆ close_device_vfunc()

virtual bool Gst::AudioRingBuffer::close_device_vfunc | ( |  | ) |
| virtual

Virtual function to close the device.

## ◆ commit()

guint Gst::AudioRingBuffer::commit | ( | guint64 & | sample,
|  | const std::vector< guint8 > & | 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 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.

## ◆ commit_vfunc()

virtual guint Gst::AudioRingBuffer::commit_vfunc | ( | guint64 & | sample,
|  | const std::vector< guint8 > & | data,
|  | int | in_samples,
|  | int | out_samples,
|  | int & | accum
| ) |  |
| virtual

Virtual function to write samples into the ring buffer.

## ◆ convert()

bool Gst::AudioRingBuffer::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.

## ◆ delay_vfunc()

virtual guint Gst::AudioRingBuffer::delay_vfunc | ( |  | ) |
| virtual

Virtual function to get number of samples queued in device.

## ◆ device_is_open()

bool Gst::AudioRingBuffer::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.

## ◆ get_delay()

guint Gst::AudioRingBuffer::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.

## ◆ get_samples_done()

guint64 Gst::AudioRingBuffer::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.

## ◆ get_type()

static GType Gst::AudioRingBuffer::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GstAudioRingBuffer* Gst::AudioRingBuffer::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GstAudioRingBuffer* Gst::AudioRingBuffer::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GstAudioRingBuffer* Gst::AudioRingBuffer::gobj_copy | ( |  | ) |

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

## ◆ is_acquired()

bool Gst::AudioRingBuffer::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.

## ◆ is_active()

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

Check if buf is activated.

MT safe.

Returns
  `true` if the device is active.

## ◆ is_flushing()

gboolean Gst::AudioRingBuffer::is_flushing | ( |  | ) |

Check if buf is flushing.

MT safe.

Returns
  `true` if the device is flushing.

## ◆ open_device()

bool Gst::AudioRingBuffer::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.

## ◆ open_device_vfunc()

virtual bool Gst::AudioRingBuffer::open_device_vfunc | ( |  | ) |
| virtual

Virtual function to open the device.

Don't set any params or allocate anything.

## ◆ operator=()

AudioRingBuffer& Gst::AudioRingBuffer::operator= | ( | AudioRingBuffer&& | src | ) |
| noexcept

## ◆ parse_caps()

static bool Gst::AudioRingBuffer::parse_caps | ( | Gst::AudioRingBufferSpec& | p1,
|  | const Glib::RefPtr< Gst::Caps >& | caps
| ) |  |
| static

Parse caps into p1.

Parameters

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

Returns
  `true` if the caps could be parsed.

## ◆ pause()

bool Gst::AudioRingBuffer::pause | ( |  | ) |

Pause processing samples from the ringbuffer.

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

MT safe.

## ◆ pause_vfunc()

virtual bool Gst::AudioRingBuffer::pause_vfunc | ( |  | ) |
| virtual

Virtual function to pause processing of samples.

## ◆ prepare_read()

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

Returns a pointer to memory where the data from segment segment can be found.

This function is mostly used by subclasses.

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.

## ◆ read()

guint Gst::AudioRingBuffer::read | ( | guint64 | sample,
|  | const std::vector< guint8 > & | data,
|  | guint | len,
|  | Gst::ClockTime& | timestamp
| ) |  |

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.

timestamp will return the timestamp associated with the data returned.

Parameters

  sample | The sample position of the data.
  data | Where the data should be read.
  len | The number of samples in data to read.
  timestamp | Where the timestamp is returned.

Returns
  The number of samples read from the ringbuffer or -1 on error.

MT safe.

## ◆ release()

bool Gst::AudioRingBuffer::release | ( |  | ) |

Free the resources of the ringbuffer.

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

MT safe.

## ◆ release_vfunc()

virtual bool Gst::AudioRingBuffer::release_vfunc | ( |  | ) |
| virtual

Virtual function to free resources of the ring buffer.

## ◆ resume_vfunc()

virtual bool Gst::AudioRingBuffer::resume_vfunc | ( |  | ) |
| virtual

Virtual function to resume processing of samples after pause.

## ◆ set_channel_position()

void Gst::AudioRingBuffer::set_channel_position | ( | const Gst::AudioChannelPosition& | position | ) |

Tell the ringbuffer about the device's channel positions.

This must be called in when the ringbuffer is acquired.

Parameters

  position | The device channel positions.

## ◆ set_fill_slot()

void Gst::AudioRingBuffer::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.

## ◆ set_flushing()

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

Set the ringbuffer to flushing mode or normal mode.

MT safe.

Parameters

  flushing | The new mode.

## ◆ set_may_start()

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

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

MT safe.

Parameters

  allowed | The new value.

## ◆ set_sample()

void Gst::AudioRingBuffer::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.

## ◆ set_timestamp()

void Gst::AudioRingBuffer::set_timestamp | ( | gint | readseg,
|  | ClockTime | timestamp
| ) |  |

## ◆ start()

bool Gst::AudioRingBuffer::start | ( |  | ) |

Start processing samples from the ringbuffer.

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

MT safe.

## ◆ start_vfunc()

virtual bool Gst::AudioRingBuffer::start_vfunc | ( |  | ) |
| virtual

Virtual function to start processing of samples.

## ◆ stop()

bool Gst::AudioRingBuffer::stop | ( |  | ) |

Stop processing samples from the ringbuffer.

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

MT safe.

## ◆ stop_vfunc()

virtual bool Gst::AudioRingBuffer::stop_vfunc | ( |  | ) |
| virtual

Virtual function to stop processing of samples.

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gst::AudioRingBuffer > wrap | ( | GstAudioRingBuffer * | 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.