Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
Safe Haskell | None |
Language | Haskell2010 |
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.
Synopsis
- newtype AudioRingBuffer = AudioRingBuffer (ManagedPtr AudioRingBuffer)
- class (GObject o, IsDescendantOf AudioRingBuffer o) => IsAudioRingBuffer o
- toAudioRingBuffer :: (MonadIO m, IsAudioRingBuffer o) => o -> m AudioRingBuffer
- noAudioRingBuffer :: Maybe AudioRingBuffer
- audioRingBufferAcquire :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> AudioRingBufferSpec -> m Bool
- audioRingBufferActivate :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Bool -> m Bool
- audioRingBufferAdvance :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Word32 -> m ()
- audioRingBufferClear :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Int32 -> m ()
- audioRingBufferClearAll :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m ()
- audioRingBufferCloseDevice :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferCommit :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Word64 -> ByteString -> Int32 -> Int32 -> m (Word32, Int32)
- audioRingBufferConvert :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Format -> Int64 -> Format -> m (Bool, Int64)
- audioRingBufferDebugSpecBuff :: (HasCallStack, MonadIO m) => AudioRingBufferSpec -> m ()
- audioRingBufferDebugSpecCaps :: (HasCallStack, MonadIO m) => AudioRingBufferSpec -> m ()
- audioRingBufferDelay :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Word32
- audioRingBufferDeviceIsOpen :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferIsAcquired :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferIsActive :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferIsFlushing :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferMayStart :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Bool -> m ()
- audioRingBufferOpenDevice :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferParseCaps :: (HasCallStack, MonadIO m) => AudioRingBufferSpec -> Caps -> m Bool
- audioRingBufferPause :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferPrepareRead :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m (Bool, Int32, ByteString)
- audioRingBufferRead :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Word64 -> ByteString -> m (Word32, Word64)
- audioRingBufferRelease :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferSamplesDone :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Word64
- audioRingBufferSetCallback :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Maybe AudioRingBufferCallback -> m ()
- audioRingBufferSetChannelPositions :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> [AudioChannelPosition] -> m ()
- audioRingBufferSetFlushing :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Bool -> m ()
- audioRingBufferSetSample :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Word64 -> m ()
- audioRingBufferSetTimestamp :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Int32 -> Word64 -> m ()
- audioRingBufferStart :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
- audioRingBufferStop :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> m Bool
Exported types
newtype AudioRingBuffer Source #
Memory-managed wrapper type.
Instances
GObject AudioRingBuffer Source # | |
Defined in GI.GstAudio.Objects.AudioRingBuffer gobjectType :: IO GType # | |
HasParentTypes AudioRingBuffer Source # | |
Defined in GI.GstAudio.Objects.AudioRingBuffer | |
type ParentTypes AudioRingBuffer Source # | |
Defined in GI.GstAudio.Objects.AudioRingBuffer |
class (GObject o, IsDescendantOf AudioRingBuffer o) => IsAudioRingBuffer o Source #
Type class for types which can be safely cast to AudioRingBuffer
, for instance with toAudioRingBuffer
.
Instances
(GObject o, IsDescendantOf AudioRingBuffer o) => IsAudioRingBuffer o Source # | |
Defined in GI.GstAudio.Objects.AudioRingBuffer |
toAudioRingBuffer :: (MonadIO m, IsAudioRingBuffer o) => o -> m AudioRingBuffer Source #
Cast to AudioRingBuffer
, for types for which this is known to be safe. For general casts, use castTo
.
noAudioRingBuffer :: Maybe AudioRingBuffer Source #
A convenience alias for Nothing
:: Maybe
AudioRingBuffer
.
Methods
acquire
audioRingBufferAcquire Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> AudioRingBufferSpec |
|
-> m Bool | Returns: TRUE if the device could be acquired, FALSE on error. MT safe. |
Allocate the resources for the ringbuffer. This function fills
in the data pointer of the ring buffer with a valid Buffer
to which samples can be written.
activate
audioRingBufferActivate Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Bool |
|
-> m Bool | Returns: TRUE if the device could be activated in the requested mode, FALSE on error. |
Activate buf
to start or stop pulling data.
MT safe.
advance
audioRingBufferAdvance Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Word32 |
|
-> m () |
Subclasses should call this function to notify the fact that
advance
segments are now processed by the device.
MT safe.
clear
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Int32 |
|
-> m () |
Clear the given segment of the buffer with silence samples. This function is used by subclasses.
MT safe.
clearAll
audioRingBufferClearAll Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m () |
Fill the ringbuffer with silence.
MT safe.
closeDevice
audioRingBufferCloseDevice Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device could be closed, FALSE on error. MT safe. |
Close the audio device associated with the ring buffer. The ring buffer
should already have been released via audioRingBufferRelease
.
commit
audioRingBufferCommit Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Word64 |
|
-> ByteString |
|
-> Int32 |
|
-> Int32 |
|
-> m (Word32, Int32) | Returns: The number of samples written to the ringbuffer or -1 on error. The
number of samples written can be less than |
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.
convert
audioRingBufferConvert Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Format |
|
-> Int64 |
|
-> Format |
|
-> m (Bool, Int64) | Returns: TRUE if the conversion succeeded. |
Convert srcVal
in srcFmt
to the equivalent value in destFmt
. The result
will be put in destVal
.
debugSpecBuff
audioRingBufferDebugSpecBuff Source #
:: (HasCallStack, MonadIO m) | |
=> AudioRingBufferSpec |
|
-> m () |
Print debug info about the buffer sized in spec
to the debug log.
debugSpecCaps
audioRingBufferDebugSpecCaps Source #
:: (HasCallStack, MonadIO m) | |
=> AudioRingBufferSpec |
|
-> m () |
Print debug info about the parsed caps in spec
to the debug log.
delay
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Word32 | Returns: The number of samples queued in the audio device. MT safe. |
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.
deviceIsOpen
audioRingBufferDeviceIsOpen Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device was open, FALSE if it was closed. MT safe. |
Checks the status of the device associated with the ring buffer.
isAcquired
audioRingBufferIsAcquired Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the ringbuffer is acquired, FALSE on error. MT safe. |
Check if the ringbuffer is acquired and ready to use.
isActive
audioRingBufferIsActive Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device is active. |
Check if buf
is activated.
MT safe.
isFlushing
audioRingBufferIsFlushing Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device is flushing. |
Check if buf
is flushing.
MT safe.
mayStart
audioRingBufferMayStart Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Bool |
|
-> m () |
Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples.
MT safe.
openDevice
audioRingBufferOpenDevice Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device could be opened, FALSE on error. MT safe. |
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.
parseCaps
audioRingBufferParseCaps Source #
:: (HasCallStack, MonadIO m) | |
=> AudioRingBufferSpec |
|
-> Caps |
|
-> m Bool | Returns: TRUE if the caps could be parsed. |
Parse caps
into spec
.
pause
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device could be paused, FALSE on error. MT safe. |
Pause processing samples from the ringbuffer.
prepareRead
audioRingBufferPrepareRead Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m (Bool, Int32, ByteString) | Returns: FALSE if the buffer is not started. MT safe. |
Returns a pointer to memory where the data from segment segment
can be found. This function is mostly used by subclasses.
read
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Word64 |
|
-> ByteString |
|
-> m (Word32, Word64) | Returns: The number of samples read from the ringbuffer or -1 on error. MT safe. |
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.
release
audioRingBufferRelease Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device could be released, FALSE on error. MT safe. |
Free the resources of the ringbuffer.
samplesDone
audioRingBufferSamplesDone Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Word64 | Returns: The number of samples processed by the ringbuffer. MT safe. |
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 audioRingBufferDelay
).
setCallback
audioRingBufferSetCallback Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Maybe AudioRingBufferCallback |
|
-> m () |
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.
Since: 1.12
setChannelPositions
audioRingBufferSetChannelPositions Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> [AudioChannelPosition] |
|
-> m () |
Tell the ringbuffer about the device's channel positions. This must be called in when the ringbuffer is acquired.
setFlushing
audioRingBufferSetFlushing Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Bool |
|
-> m () |
Set the ringbuffer to flushing mode or normal mode.
MT safe.
setSample
audioRingBufferSetSample Source #
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> Word64 |
|
-> m () |
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.
setTimestamp
audioRingBufferSetTimestamp :: (HasCallStack, MonadIO m, IsAudioRingBuffer a) => a -> Int32 -> Word64 -> m () Source #
No description available in the introspection data.
start
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device could be started, FALSE on error. MT safe. |
Start processing samples from the ringbuffer.
stop
:: (HasCallStack, MonadIO m, IsAudioRingBuffer a) | |
=> a |
|
-> m Bool | Returns: TRUE if the device could be stopped, FALSE on error. MT safe. |
Stop processing samples from the ringbuffer.