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("org.javagi.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.

  • Constructor Details

    • AudioRingBuffer

      public AudioRingBuffer(MemorySegment address)
      Create a AudioRingBuffer instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • AudioRingBuffer

      public AudioRingBuffer()
      Create 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()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GstObject
      Returns:
      the instance as if it were its parent type

    • 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, @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, @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