gstreamermm 0.10.10.1
Public Types | Public Member Functions | Static Public Member Functions | Related Functions
Gst::RingBuffer Class Reference

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

Inheritance diagram for Gst::RingBuffer:
Inheritance graph
[legend]
Collaboration diagram for Gst::RingBuffer:
Collaboration graph
[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 a pointer to memory where the data from segment segment can be found.
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& p1, const Glib::RefPtr< Gst::Caps >& caps)
 Parse caps into spec.

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Gst::RingBufferwrap (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:
specThe 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:
activeThe new mode.
Returns:
true if the device could be activated in the requested mode, false on error.
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:
advanceThe 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:
segmentThe 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,
guint  len 
)

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

Parameters:
sampleThe sample position of the data.
dataThe data to commit.
lenThe number of samples in the data to commit.
Returns:
The number of samples written to the ringbuffer or -1 on error.

MT safe.

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:
sampleThe sample position of the data.
dataThe data to commit.
in_samplesThe number of samples in the data to commit.
out_samplesThe number of samples to write to the ringbuffer.
accumAccumulator 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.
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_fmtThe source format.
src_valThe source value.
dest_fmtThe destination format.
dest_valA location to store the converted value.
Returns:
true if the conversion succeeded.
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.

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

Provides access to the underlying C GObject.

Reimplemented from Gst::Object.

const GstRingBuffer* Gst::RingBuffer::gobj ( ) const [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.
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 p1,
const Glib::RefPtr< Gst::Caps >&  caps 
) [static]

Parse caps into spec.

Parameters:
specA spec.
capsA 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 a pointer to memory where the data from segment segment can be found.

This function is mostly used by subclasses.

Parameters:
segmentThe segment to read.
readptrThe pointer to the memory where samples can be read.
lenThe 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:
sampleThe sample position of the data.
dataWhere the data should be read.
lenThe 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:
slotThe fill slot to set.
void Gst::RingBuffer::set_flushing ( bool  flushing)

Set the ringbuffer to flushing mode or normal mode.

MT safe.

Parameters:
flushingThe 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.

Parameters:
allowedThe 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:
sampleThe 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:
objectThe C instance.
take_copyFalse 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: