omni::audio::experimental::ICaptureStream

Defined in omni/audio/experimental/IAudioCapture.h

class ICaptureStream : public omni::core::Generated<omni::audio::experimental::ICaptureStream_abi>

An individual audio capture stream.

Public Functions

inline void *cast(omni::core::TypeId id) noexcept

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

inline void acquire() noexcept

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline void release() noexcept

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

Protected Functions

virtual AudioResult start_abi(CaptureStreamStartFlags flags) noexcept = 0

Starts capturing audio data from the stream.

Remark

Audio streams are in a stopped state when they’re created. You must call start() to start recording audio.

Remark

Without fCaptureStreamStartFlagOneShot, the stream will perform looping capture. This means that once the ring buffer has been filled, audio will start being recorded from the start of the buffer again.

Remark

Looping audio will not overwrite unread parts of the ring buffer. Only parts of the buffer that have been unlocked can be overwritten by the audio system. Data written into the ring buffer must be unlocked periodically when using looping capture or the ring buffer will fill up and the device will overrun.

Thread Safety: Calls to this function cannot occur concurrently with other calls to ICaptureStream_abi::start_abi() or ICaptureStream_abi::stop_abi().

Parameters: flags – [in] Flags to alter the recording behavior.
Returns: carb::audio::AudioResult::eOk if the capture is successfully started.
Returns: An AudioResult error code if the stream could not be started.

virtual AudioResult stop_abi(CaptureStreamStopFlags flags) noexcept = 0

Stop capturing audio data from the stream.

Remark

This will stop capturing audio. Any audio data that would have been captured between this point and the next call to ICaptureStream_abi::start_abi() will be lost.

Remark

If there is unread data in the buffer, that data can still be read with lock() after the stream is stopped.

Thread Safety: Calls to this function cannot occur concurrently with other calls to ICaptureStream_abi::start_abi() or ICaptureStream_abi::stop_abi().

Note

If fCaptureStreamStopFlagSync was not specified, the stop call will not sync with the device so you could still receive callbacks after.

Note

CC-1180: You cannot use fCaptureStreamStopFlagSync from a callback.

Parameters: flags – [in] Flags to alter the stopping behavior.
Returns: carb::audio::AudioResult::eOk if the capture was successfully stopped.
Returns: carb::audio::AudioResult::eNotAllowed if the stream was already stopped.
Returns: An AudioResult error code if something else went wrong. The stream is likely broken in this case.

virtual bool isCapturing_abi() noexcept = 0

Check if the stream is still capturing data.

Returns: true if the stream is still capturing.
Returns: false if the stream is stopped. Callbacks will no longer be sent if false was returned unless the strema was stoped with ICaptureStream_abi::stop_abi() was called without fCaptureStreamStopFlagSync.

virtual AudioResult getAvailableFrames_abi(size_t *available) noexcept = 0

Get the available number of frames to be read.

Remark

This will check how much data is available to be read from the buffer. This call is only valid when polling style recording is in use.

Parameters: available – [out] The number of frames that can be read from the buffer.
Returns: carb::audio::AudioResult::eOk if the frame count was retrieved successfully.
Returns: carb::audio::AudioResult::eOverrun if data has not been read fast enough and the buffer filled up.
Returns: carb::audio::AudioResult::eNotAllowed if callback recording is being used.
Returns: An AudioResult error code if the operation fails for any other reason.

virtual AudioResult lock_abi(size_t request, const void **region, size_t *received) noexcept = 0

Lock the next chunk of the buffer to be read.

Remark

This is used to get data from the capture stream when polling style recording is being used (ie: there is no data callback). When using this style of recording, portions of the buffer must be periodically locked and unlocked.

Remark

This retrieves the next portion of the buffer. This portion of the buffer is considered to be locked until ICaptureStream_abi::unlock_abi() is called. Only one region of the buffer can be locked at a time. When using a looping capture, the caller should ensure that data is unlocked before the buffer fills up or overruns may occur.

Parameters

request – [in] The length of the buffer to lock, in frames. This may be 0 to lock as much data as possible. This does not need to be a multiple of the fragment length. If you need to convert bytes to frames, you can use carb::audio::convertUnits() or carb::audio::framesToBytes() (note that this is slow due to requiring a division).
region – [out] Receives the audio data. This can be nullptr to query the available data in the buffer, rather than locking it. This buffer can be held until unlock() is called; after unlock is called, the stream can start writing into this buffer.
received – [out] The length of data available in buffer, in frames. This will not exceed request. Due to the fact that a ring buffer is used, you may have more data in the buffer than is returned in one call; a second call would be needed to read the full buffer. If you need to convert this to bytes, you can use carb::audio::convertUnits() or carb::audio::framesToBytes().

Returns

carb::audio::AudioResult::eOk if the requested region is successfully locked.

Returns

carb::audio::AudioResult::eOutOfMemory if there is no audio data available in the buffer yet.

Returns

carb::audio::AudioResult::eNotAllowed if a region is already locked and needs to be unlocked.

Returns

carb::audio::AudioResult::eNotAllowed if the stream is using callback style recording.

Returns

carb::audio::AudioResult::eOverrun if data has not been read fast enough and the underlying device has overrun. This will happen on some audio systems (e.g. ALSA) if the capture buffer fills up. This can also happen on some audio systems sporadically if the device’s timing characteristics are too aggressive.

Returns

an carb::audio::AudioResult::e* error code if the region could not be locked.

virtual AudioResult unlock_abi(size_t consumed) noexcept = 0

Unlocks a previously locked region of the buffer.

Remark

This unlocks a region of the buffer that was locked with a previous call to ICaptureStream_abi::lock_abi(). Now that this region is unlocked, the device can start writing to it, so the caller should no longer access that region. Once the buffer is unlocked, a new region may be locked with ICaptureStream_abi::lock_abi().

Note

If the locked region is not fully unlocked, the part of the region that was not unlocked will be returned on the next call to ICaptureStream_abi::lock_abi(). A second call to unlock cannot be made in this situation, it will fail.

Parameters: consumed – [in] The number of frames in the previous buffer that were consumed. Any frames that were not consumed will be returned in future ICaptureStream_abi::lock_abi() calls. 0 is valid here if you want to have the same locked region returned on the next lock() call.
Returns: carb::audio::AudioResult::eOk if the region is successfully unlocked.
Returns: carb::audio::AudioResult::eOutOfRange if consumed was larger than the locked region.
Returns: carb::audio::AudioResult::eNotAllowed if no region is currently locked.
Returns: an carb::audio::AudioResult::e* error code if the region could not be unlocked.

virtual size_t getBufferSize_abi() noexcept = 0

Retrieve the size of the capture buffer.

Remark

If your code is dependent on the buffer’s actual size, it is better to retrieve it with this function since the buffer size used with device creation can be adjusted.

Returns: The size of the capture buffer, in frames. You can use ICaptureStream_abi::getSoundFormat_abi() and carb::audio::convertUnits() to convert to bytes or other units.

virtual size_t getFragmentCount_abi() noexcept = 0

Retrieve the number of fragments used in this stream.

Returns: The number of buffer fragments. This is the number of regions the recording buffer is divided into.

virtual void getSoundFormat_abi(SoundFormat *format) noexcept = 0

Retrieve the format of the audio being captured.

Parameters: format – [out] The format of the audio being captured. This may not be nullptr.

virtual AudioResult reset_abi() noexcept = 0

Clear any data that is currently in the recording buffer.

Remark

This is a quick way to get rid of any data that is left in the buffer. This will also reset the write position on the buffer back to 0, so the next lock call will return the start of the buffer (this can be useful if you want to do a one shot capture of the entire buffer).

Note

If this is called while the capture stream is recording, the stream will be paused before it is reset.

Returns: carb::audio::AudioResult::eOk if the buffer was successfully cleared.
Returns: an carb::audio::AudioResult::e* error code if the buffer could not be cleared.

virtual void *cast_abi(TypeId id) noexcept = 0

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

virtual void acquire_abi() noexcept = 0

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

virtual void release_abi() noexcept = 0

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.