Package org.freedesktop.gstreamer.audio

Class AudioRingBuffer

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gobject.InitiallyUnowned

org.freedesktop.gstreamer.gst.GstObject

org.freedesktop.gstreamer.audio.AudioRingBuffer

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

AudioRingBuffer.AudioRingBuffer$Impl

@Generated("io.github.jwharm.JavaGI")
public abstract class AudioRingBuffer
extends GstObject

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AudioRingBuffer.AudioRingBuffer$Impl	The AudioRingBuffer$Impl type represents a native instance of the abstract AudioRingBuffer class.
static class	AudioRingBuffer.AudioRingBufferClass	The vmethods that subclasses can override to implement the ringbuffer.
static class	AudioRingBuffer.Builder<B extends AudioRingBuffer.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.gst.GstObject

GstObject.DeepNotifyCallback, GstObject.Object$Impl, GstObject.ObjectClass

Nested classes/interfaces inherited from class org.gnome.gobject.InitiallyUnowned

InitiallyUnowned.InitiallyUnownedClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback

Constructor Summary

Constructors

Constructor	Description
AudioRingBuffer()	Creates a new AudioRingBuffer.
AudioRingBuffer(MemorySegment address)	Create a AudioRingBuffer proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
boolean	acquire(AudioRingBufferSpec spec)	Allocate the resources for the ringbuffer.
boolean	activate(boolean active)	Activate this AudioRingBuffer to start or stop pulling data.
void	advance(int advance)	Subclasses should call this function to notify the fact that advance segments are now processed by the device.
protected AudioRingBuffer	asParent()	Returns this instance as if it were its parent type.
void	clear(int segment)	Clear the given segment of the buffer with silence samples.
void	clearAll()	Clear all samples from the ringbuffer.
boolean	closeDevice()	Close the audio device associated with the ring buffer.
int	commit(Out<Long> sample, @org.jspecify.annotations.Nullable byte @Nullable [] data, int outSamples, Out<Integer> accum)	Commit inSamples samples pointed to by data to the ringbuffer buf.
boolean	convert(Format srcFmt, long srcVal, Format destFmt, Out<Long> destVal)	Convert srcVal in srcFmt to the equivalent value in destFmt. The result will be put in destVal.
static void	debugSpecBuff(AudioRingBufferSpec spec)	Print debug info about the buffer sized in spec to the debug log.
static void	debugSpecCaps(AudioRingBufferSpec spec)	Print debug info about the parsed caps in spec to the debug log.
int	delay()	Get the number of samples queued in the audio device.
boolean	deviceIsOpen()	Checks the status of the device associated with the ring buffer.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
long	getSegbase()	Gets the current segment base number of the ringbuffer.
long	getSegdone()	Gets the current segment number of the ringbuffer.
static @Nullable Type	getType()	Get the GType of the AudioRingBuffer class
boolean	isAcquired()	Check if the ringbuffer is acquired and ready to use.
boolean	isActive()	Check if this AudioRingBuffer is activated.
boolean	isFlushing()	Check if this AudioRingBuffer is flushing.
void	mayStart(boolean allowed)	Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples.
boolean	openDevice()	Open the audio device associated with the ring buffer.
static boolean	parseCaps(AudioRingBufferSpec spec, Caps caps)	Parse caps into spec.
boolean	pause()	Pause processing samples from the ringbuffer.
boolean	prepareRead(Out<Integer> segment, @Nullable Out<byte[]> readptr)	Returns a pointer to memory where the data from segment segment can be found.
int	read(long sample, @org.jspecify.annotations.Nullable byte @Nullable [] data, 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.
boolean	release()	Free the resources of the ringbuffer.
protected boolean	resume()	resume processing of samples after pause
long	samplesDone()	Get the number of samples that were processed by the ringbuffer since it was last started.
void	setCallback(@Nullable AudioRingBufferCallback cb)	Sets the given callback function on the buffer.
void	setChannelPositions(@Nullable AudioChannelPosition @Nullable [] position)	Tell the ringbuffer about the device's channel positions.
void	setErrored()	Mark the ringbuffer as errored after it has started.
void	setFlushing(boolean flushing)	Set the ringbuffer to flushing mode or normal mode.
void	setSample(long sample)	Make sure that the next sample written to the device is accounted for as being the sample sample written to the device.
void	setSegdone(long segdone)	Sets the current segment number of the ringbuffer.
void	setTimestamp(int readseg, ClockTime timestamp)
boolean	start()	Start processing samples from the ringbuffer.
boolean	stop()	Stop processing samples from the ringbuffer.

Methods inherited from class org.freedesktop.gstreamer.gst.GstObject

addControlBinding, checkUniqueness, deepNotify, defaultDeepNotify, defaultError, emitDeepNotify, getControlBinding, getControlRate, getGValueArray, getName, getParent, getPathString, getValue, getValueArray, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, onDeepNotify, ref, refSink, removeControlBinding, replace, setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setName, setParent, suggestNextSync, syncValues, unparent, unref

Methods inherited from class org.gnome.gobject.InitiallyUnowned

builder

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AudioRingBuffer

public AudioRingBuffer(MemorySegment address)

Create a AudioRingBuffer proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

AudioRingBuffer

public AudioRingBuffer()

Creates a new AudioRingBuffer.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the AudioRingBuffer class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected AudioRingBuffer asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GstObject

debugSpecBuff

public static void debugSpecBuff(AudioRingBufferSpec spec)

Print debug info about the buffer sized in spec to the debug log.

Parameters:

spec - the spec to debug

debugSpecCaps

public static void debugSpecCaps(AudioRingBufferSpec spec)

Print debug info about the parsed caps in spec to the debug log.

Parameters:

spec - the spec to debug

parseCaps

public static boolean parseCaps(AudioRingBufferSpec spec,
 Caps caps)

Parse caps into spec.

Parameters:

spec - a spec

caps - a GstCaps

Returns:

TRUE if the caps could be parsed.

acquire

public boolean acquire(AudioRingBufferSpec 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:

spec - the specs of the buffer

Returns:

TRUE if the device could be acquired, FALSE on error.

MT safe.

activate

public boolean activate(boolean active)

Activate this AudioRingBuffer 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.

advance

public void advance(int 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

public void 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

clearAll

public void clearAll()

Clear all samples from the ringbuffer.

MT safe.

closeDevice

public boolean closeDevice()

Close the audio device associated with the ring buffer. The ring buffer should already have been released via gst_audio_ring_buffer_release().

Returns:

TRUE if the device could be closed, FALSE on error.

MT safe.

commit

public int commit(Out<Long> sample,
 @org.jspecify.annotations.Nullable byte @Nullable [] data,
 int outSamples,
 Out<Integer> accum)

Commit inSamples samples pointed to by data to the ringbuffer buf.

inSamples and outSamples define the rate conversion to perform on the samples in data. For negative rates, outSamples must be negative and inSamples positive.

When outSamples is positive, the first sample will be written at position sample in the ringbuffer. When outSamples is negative, the last sample will be written to sample in reverse order.

outSamples 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

outSamples - 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 outSamples when this AudioRingBuffer was interrupted with a flush or stop.

convert

public boolean convert(Format srcFmt,
 long srcVal,
 Format destFmt,
 Out<Long> destVal)

Convert srcVal in srcFmt to the equivalent value in destFmt. The result will be put in destVal.

Parameters:

srcFmt - the source format

srcVal - the source value

destFmt - the destination format

destVal - a location to store the converted value

Returns:

TRUE if the conversion succeeded.

delay

public int delay()

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.

Returns:

The number of samples queued in the audio device.

MT safe.

deviceIsOpen

public boolean deviceIsOpen()

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.

getSegbase

public long getSegbase()

Gets the current segment base number of the ringbuffer.

MT safe.

Returns:

Current segment base number of the ringbuffer.

Since:

1.26

getSegdone

public long getSegdone()

Gets the current segment number of the ringbuffer.

MT safe.

Returns:

Current segment number of the ringbuffer.

Since:

1.26

isAcquired

public boolean isAcquired()

Check if the ringbuffer is acquired and ready to use.

Returns:

TRUE if the ringbuffer is acquired, FALSE on error.

MT safe.

isActive

public boolean isActive()

Check if this AudioRingBuffer is activated.

MT safe.

Returns:

TRUE if the device is active.

isFlushing

public boolean isFlushing()

Check if this AudioRingBuffer is flushing.

MT safe.

Returns:

TRUE if the device is flushing.

mayStart

public void mayStart(boolean 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

openDevice

public boolean openDevice()

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.

pause

public boolean pause()

Pause processing samples from the ringbuffer.

Returns:

TRUE if the device could be paused, FALSE on error.

MT safe.

prepareRead

public boolean prepareRead(Out<Integer> segment,
 @Nullable Out<byte[]> readptr)

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

Returns:

FALSE if the buffer is not started.

MT safe.

read

public int read(long sample,
 @org.jspecify.annotations.Nullable byte @Nullable [] data,
 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

timestamp - where the timestamp is returned

Returns:

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

MT safe.

release

public boolean release()

Free the resources of the ringbuffer.

Returns:

TRUE if the device could be released, FALSE on error.

MT safe.

samplesDone

public long samplesDone()

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

Returns:

The number of samples processed by the ringbuffer.

MT safe.

setCallback

public void setCallback(@Nullable AudioRingBufferCallback cb)

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:

cb - the callback to set

Since:

1.12

setChannelPositions

public void setChannelPositions(@Nullable AudioChannelPosition @Nullable [] 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

setErrored

public void setErrored()

Mark the ringbuffer as errored after it has started.

MT safe.

Since:

1.24

setFlushing

public void setFlushing(boolean flushing)

Set the ringbuffer to flushing mode or normal mode.

MT safe.

Parameters:

flushing - the new mode

setSample

public void setSample(long 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

setSegdone

public void setSegdone(long segdone)

Sets the current segment number of the ringbuffer.

MT safe.

Parameters:

segdone - the segment number to set

Since:

1.26

setTimestamp

public void setTimestamp(int readseg,
 ClockTime timestamp)

start

public boolean start()

Start processing samples from the ringbuffer.

Returns:

TRUE if the device could be started, FALSE on error.

MT safe.

stop

public boolean stop()

Stop processing samples from the ringbuffer.

Returns:

TRUE if the device could be stopped, FALSE on error.

MT safe.

resume

protected boolean resume()

resume processing of samples after pause