GstAudioRingBuffer
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.
GstAudioRingBuffer
GObject ╰──GInitiallyUnowned ╰──GstObject ╰──GstAudioRingBuffer
The ringbuffer base class structure.
Members
object
(GstObject)
–
cond
(GCond)
–
used to signal start/stop/pause/resume actions
open
(gboolean)
–
boolean indicating that the ringbuffer is open
acquired
(gboolean)
–
boolean indicating that the ringbuffer is acquired
memory
(guint8 *)
–
data in the ringbuffer
size
(gsize)
–
size of data in the ringbuffer
spec
(GstAudioRingBufferSpec)
–
format and layout of the ringbuffer data
samples_per_seg
(gint)
–
number of samples in one segment
empty_seg
(guint8 *)
–
pointer to memory holding one segment of silence samples
state
(gint)
–
state of the buffer
segdone
(gint)
–
readpointer in the ringbuffer
segbase
(gint)
–
segment corresponding to segment 0 (unused)
waiting
(gint)
–
is a reader or writer waiting for a free segment
Class structure
GstAudioRingBufferClass
The vmethods that subclasses can override to implement the ringbuffer.
Fields
parent_class
(GstObjectClass)
–
parent class
Methods
gst_audio_ring_buffer_acquire
gboolean gst_audio_ring_buffer_acquire (GstAudioRingBuffer * buf, GstAudioRingBufferSpec * 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.
TRUE if the device could be acquired, FALSE on error.
MT safe.
gst_audio_ring_buffer_activate
gboolean gst_audio_ring_buffer_activate (GstAudioRingBuffer * buf, gboolean active)
Activate buf to start or stop pulling data.
MT safe.
TRUE if the device could be activated in the requested mode, FALSE on error.
gst_audio_ring_buffer_advance
gst_audio_ring_buffer_advance (GstAudioRingBuffer * buf, guint advance)
Subclasses should call this function to notify the fact that advance segments are now processed by the device.
MT safe.
gst_audio_ring_buffer_clear
gst_audio_ring_buffer_clear (GstAudioRingBuffer * buf, gint segment)
Clear the given segment of the buffer with silence samples. This function is used by subclasses.
MT safe.
gst_audio_ring_buffer_clear_all
gst_audio_ring_buffer_clear_all (GstAudioRingBuffer * buf)
Clear all samples from the ringbuffer.
MT safe.
Parameters:
buf
–
the GstAudioRingBuffer to clear
gst_audio_ring_buffer_close_device
gboolean gst_audio_ring_buffer_close_device (GstAudioRingBuffer * buf)
Close the audio device associated with the ring buffer. The ring buffer should already have been released via gst_audio_ring_buffer_release.
Parameters:
buf
–
TRUE if the device could be closed, FALSE on error.
MT safe.
gst_audio_ring_buffer_commit
guint gst_audio_ring_buffer_commit (GstAudioRingBuffer * buf, guint64 * sample, guint8 * 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 GstAudioRingBuffer to commit
sample
(
[inout])
–
the sample position of the data
data
(
[arraylength=in_samples])
–
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
(
[inout])
–
accumulator for rate conversion.
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.
gst_audio_ring_buffer_convert
gboolean gst_audio_ring_buffer_convert (GstAudioRingBuffer * 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
–
src_fmt
–
the source format
src_val
–
the source value
dest_fmt
–
the destination format
dest_val
(
[out])
–
a location to store the converted value
TRUE if the conversion succeeded.
gst_audio_ring_buffer_delay
guint gst_audio_ring_buffer_delay (GstAudioRingBuffer * 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 transferred 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 transferred to the ringbuffer.
Parameters:
buf
–
the GstAudioRingBuffer to query
The number of samples queued in the audio device.
MT safe.
gst_audio_ring_buffer_device_is_open
gboolean gst_audio_ring_buffer_device_is_open (GstAudioRingBuffer * buf)
Checks the status of the device associated with the ring buffer.
Parameters:
buf
–
TRUE if the device was open, FALSE if it was closed.
MT safe.
gst_audio_ring_buffer_get_segbase
guint64 gst_audio_ring_buffer_get_segbase (GstAudioRingBuffer * buf)
Gets the current segment base number of the ringbuffer.
MT safe.
Parameters:
buf
–
the GstAudioRingBuffer to use
Current segment base number of the ringbuffer.
Since : 1.26
gst_audio_ring_buffer_get_segdone
guint64 gst_audio_ring_buffer_get_segdone (GstAudioRingBuffer * buf)
Gets the current segment number of the ringbuffer.
MT safe.
Parameters:
buf
–
the GstAudioRingBuffer to use
Current segment number of the ringbuffer.
Since : 1.26
gst_audio_ring_buffer_is_acquired
gboolean gst_audio_ring_buffer_is_acquired (GstAudioRingBuffer * buf)
Check if the ringbuffer is acquired and ready to use.
Parameters:
buf
–
the GstAudioRingBuffer to check
TRUE if the ringbuffer is acquired, FALSE on error.
MT safe.
gst_audio_ring_buffer_is_active
gboolean gst_audio_ring_buffer_is_active (GstAudioRingBuffer * buf)
Check if buf is activated.
MT safe.
Parameters:
buf
–
TRUE if the device is active.
gst_audio_ring_buffer_is_flushing
gboolean gst_audio_ring_buffer_is_flushing (GstAudioRingBuffer * buf)
Check if buf is flushing.
MT safe.
Parameters:
buf
–
TRUE if the device is flushing.
gst_audio_ring_buffer_may_start
gst_audio_ring_buffer_may_start (GstAudioRingBuffer * buf, gboolean allowed)
Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples.
MT safe.
gst_audio_ring_buffer_open_device
gboolean gst_audio_ring_buffer_open_device (GstAudioRingBuffer * 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
–
TRUE if the device could be opened, FALSE on error.
MT safe.
gst_audio_ring_buffer_pause
gboolean gst_audio_ring_buffer_pause (GstAudioRingBuffer * buf)
Pause processing samples from the ringbuffer.
Parameters:
buf
–
the GstAudioRingBuffer to pause
TRUE if the device could be paused, FALSE on error.
MT safe.
gst_audio_ring_buffer_prepare_read
gboolean gst_audio_ring_buffer_prepare_read (GstAudioRingBuffer * 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 GstAudioRingBuffer to read from
segment
(
[out])
–
the segment to read
readptr
–
(out) (array length=len): the pointer to the memory where samples can be read
len
(
[out])
–
the number of bytes to read
FALSE if the buffer is not started.
MT safe.
gst_audio_ring_buffer_read
guint gst_audio_ring_buffer_read (GstAudioRingBuffer * buf, guint64 sample, guint8 * data, guint len, GstClockTime * 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:
buf
–
the GstAudioRingBuffer to read from
sample
–
the sample position of the data
data
(
[arraylength=len])
–
where the data should be read
len
–
the number of samples in data to read
timestamp
(
[out])
–
where the timestamp is returned
The number of samples read from the ringbuffer or -1 on error.
MT safe.
gst_audio_ring_buffer_release
gboolean gst_audio_ring_buffer_release (GstAudioRingBuffer * buf)
Free the resources of the ringbuffer.
Parameters:
buf
–
the GstAudioRingBuffer to release
TRUE if the device could be released, FALSE on error.
MT safe.
gst_audio_ring_buffer_samples_done
guint64 gst_audio_ring_buffer_samples_done (GstAudioRingBuffer * 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_audio_ring_buffer_delay).
Parameters:
buf
–
the GstAudioRingBuffer to query
The number of samples processed by the ringbuffer.
MT safe.
gst_audio_ring_buffer_set_callback
gst_audio_ring_buffer_set_callback (GstAudioRingBuffer * buf, GstAudioRingBufferCallback 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 GstAudioRingBuffer to set the callback on
cb
(
[allow-none])
–
the callback to set
user_data
–
user data passed to the callback
gst_audio_ring_buffer_set_callback_full
gst_audio_ring_buffer_set_callback_full (GstAudioRingBuffer * buf, GstAudioRingBufferCallback cb, gpointer user_data, GDestroyNotify notify)
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 GstAudioRingBuffer to set the callback on
cb
(
[allow-none])
–
the callback to set
user_data
–
user data passed to the callback
notify
–
function to be called when user_data is no longer needed
Since : 1.12
gst_audio_ring_buffer_set_channel_positions
gst_audio_ring_buffer_set_channel_positions (GstAudioRingBuffer * buf, const GstAudioChannelPosition * position)
Tell the ringbuffer about the device's channel positions. This must be called in when the ringbuffer is acquired.
gst_audio_ring_buffer_set_errored
gst_audio_ring_buffer_set_errored (GstAudioRingBuffer * buf)
Mark the ringbuffer as errored after it has started.
MT safe.
Parameters:
buf
–
the GstAudioRingBuffer that has encountered an error
Since : 1.24
gst_audio_ring_buffer_set_flushing
gst_audio_ring_buffer_set_flushing (GstAudioRingBuffer * buf, gboolean flushing)
Set the ringbuffer to flushing mode or normal mode.
MT safe.
gst_audio_ring_buffer_set_sample
gst_audio_ring_buffer_set_sample (GstAudioRingBuffer * 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.
gst_audio_ring_buffer_set_segdone
gst_audio_ring_buffer_set_segdone (GstAudioRingBuffer * buf, guint64 segdone)
Sets the current segment number of the ringbuffer.
MT safe.
Since : 1.26
gst_audio_ring_buffer_set_timestamp
gst_audio_ring_buffer_set_timestamp (GstAudioRingBuffer * buf, gint readseg, GstClockTime timestamp)
Parameters:
buf
–
readseg
–
timestamp
–
gst_audio_ring_buffer_start
gboolean gst_audio_ring_buffer_start (GstAudioRingBuffer * buf)
Start processing samples from the ringbuffer.
Parameters:
buf
–
the GstAudioRingBuffer to start
TRUE if the device could be started, FALSE on error.
MT safe.
gst_audio_ring_buffer_stop
gboolean gst_audio_ring_buffer_stop (GstAudioRingBuffer * buf)
Stop processing samples from the ringbuffer.
Parameters:
buf
–
the GstAudioRingBuffer to stop
TRUE if the device could be stopped, FALSE on error.
MT safe.
Functions
gst_audio_ring_buffer_debug_spec_buff
gst_audio_ring_buffer_debug_spec_buff (GstAudioRingBufferSpec * spec)
Print debug info about the buffer sized in spec to the debug log.
Parameters:
spec
–
the spec to debug
gst_audio_ring_buffer_debug_spec_caps
gst_audio_ring_buffer_debug_spec_caps (GstAudioRingBufferSpec * spec)
Print debug info about the parsed caps in spec to the debug log.
Parameters:
spec
–
the spec to debug
gst_audio_ring_buffer_parse_caps
gboolean gst_audio_ring_buffer_parse_caps (GstAudioRingBufferSpec * spec, GstCaps * caps)
Parse caps into spec.
TRUE if the caps could be parsed.
Virtual Methods
acquire
gboolean acquire (GstAudioRingBuffer * buf, GstAudioRingBufferSpec * spec)
allocate the resources for the ringbuffer using the given spec
Parameters:
buf
–
spec
–
activate
gboolean activate (GstAudioRingBuffer * buf, gboolean active)
activate the thread that starts pulling and monitoring the consumed segments in the device.
Parameters:
buf
–
active
–
clear_all
clear_all (GstAudioRingBuffer * buf)
Optional. Clear the entire ringbuffer. Subclasses should chain up to the parent implementation to invoke the default handler.
Parameters:
buf
–
close_device
gboolean close_device (GstAudioRingBuffer * buf)
close the device
Parameters:
buf
–
commit
guint commit (GstAudioRingBuffer * buf, guint64 * sample, guint8 * data, gint in_samples, gint out_samples, gint * accum)
write samples into the ringbuffer
Parameters:
buf
–
sample
–
data
–
in_samples
–
out_samples
–
accum
–
delay
guint delay (GstAudioRingBuffer * buf)
get number of frames queued in device
Parameters:
buf
–
open_device
gboolean open_device (GstAudioRingBuffer * buf)
open the device, don't set any params or allocate anything
Parameters:
buf
–
pause
gboolean pause (GstAudioRingBuffer * buf)
pause processing of samples
Parameters:
buf
–
release
gboolean release (GstAudioRingBuffer * buf)
free resources of the ringbuffer
Parameters:
buf
–
resume
gboolean resume (GstAudioRingBuffer * buf)
resume processing of samples after pause
Parameters:
buf
–
start
gboolean start (GstAudioRingBuffer * buf)
start processing of samples
Parameters:
buf
–
stop
gboolean stop (GstAudioRingBuffer * buf)
stop processing of samples
Parameters:
buf
–
GstAudioRingBufferSpec
The structure containing the format specification of the ringbuffer.
When type is GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DSD, the dsd_format is valid (otherwise it is unused). Also, when DSD is the sample type, only the rate, channels, position, and bpf fields in info are populated.
Members
caps
(GstCaps *)
–
The caps that generated the Spec.
type
(GstAudioRingBufferFormatType)
–
the sample type
info
(GstAudioInfo)
–
the GstAudioInfo
latency_time
(guint64)
–
the latency in microseconds
buffer_time
(guint64)
–
the total buffer size in microseconds
segsize
(gint)
–
the size of one segment in bytes
segtotal
(gint)
–
the total number of segments
seglatency
(gint)
–
number of segments queued in the lower level device, defaults to segtotal
ABI.abi.dsd_format
(GstDsdFormat)
–
the GstDsdFormat (Since: 1.24)
Function Macros
Enumerations
GstAudioRingBufferFormatType
The format of the samples in the ringbuffer.
Members
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_RAW
(0)
–
samples in linear or float
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MU_LAW
(1)
–
samples in mulaw
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_A_LAW
(2)
–
samples in alaw
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IMA_ADPCM
(3)
–
samples in ima adpcm
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG
(4)
–
samples in mpeg audio (but not AAC) format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_GSM
(5)
–
samples in gsm format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_IEC958
(6)
–
samples in IEC958 frames (e.g. AC3)
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_AC3
(7)
–
samples in AC3 format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_EAC3
(8)
–
samples in EAC3 format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DTS
(9)
–
samples in DTS format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC
(10)
–
samples in MPEG-2 AAC ADTS format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC
(11)
–
samples in MPEG-4 AAC ADTS format
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG2_AAC_RAW
(12)
–
samples in MPEG-2 AAC raw format (Since: 1.12)
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_MPEG4_AAC_RAW
(13)
–
samples in MPEG-4 AAC raw format (Since: 1.12)
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_FLAC
(14)
–
samples in FLAC format (Since: 1.12)
GST_AUDIO_RING_BUFFER_FORMAT_TYPE_DSD
(15)
–
samples in DSD format (Since: 1.24)
GstAudioRingBufferState
The state of the ringbuffer.
Members
GST_AUDIO_RING_BUFFER_STATE_STOPPED
(0)
–
The ringbuffer is stopped
GST_AUDIO_RING_BUFFER_STATE_PAUSED
(1)
–
The ringbuffer is paused
GST_AUDIO_RING_BUFFER_STATE_STARTED
(2)
–
The ringbuffer is started
GST_AUDIO_RING_BUFFER_STATE_ERROR
(3)
–
The ringbuffer has encountered an error after it has been started, e.g. because the device was disconnected (Since: 1.2)
Callbacks
GstAudioRingBufferCallback
(*GstAudioRingBufferCallback) (GstAudioRingBuffer * rbuf, guint8 * data, guint len, gpointer user_data)
This function is set with gst_audio_ring_buffer_set_callback and is called to fill the memory at data with len bytes of samples.
Parameters:
rbuf
–
data
(
[arraylength=len])
–
target to fill
len
–
amount to fill
user_data
–
user data
The results of the search are