carb::audio::NullStreamer

Defined in carb/audio/AudioStreamerUtils.h

class NullStreamer : public carb::audio::StreamerWrapper 

a null streamer implementation.

This will accept all incoming audio data but will simply ignore it. The audio processing engine will be told to continue producing data at the current rate after each buffer is written. All data formats will be accepted.

This is useful for silencing an output while still allowing audio processing based events to occur as scheduled.

Public Functions

inline NullStreamer()

inline virtual bool open(SoundFormat *format) override

sets the suggested format for this stream output.

Remark

This sets the data format that the streamer will receive its data in. The streamer may change the data format to another valid PCM data format if needed. Note that if the streamer returns a data format that cannot be converted to by the processing engine, the initialization of the output will fail. Also note that if the streamer changes the data format, this will incur a small performance penalty to convert the data to the new format.

Remark

This will be called when the audio context is first created. Once the format is accepted by both the audio context and the streamer, it will remain constant as long as the processing engine is still running on that context. When the engine is stopped (or the context is destroyed), a Streamer::close() call will be performed signaling the end of the stream. If the engine is restarted again, another open() call will be performed to signal the start of a new stream.

Note

This should not be called directly. This will be called by the audio processing engine when this streamer object is first assigned as an output on an audio context.

Parameters: format – [inout] on input, this contains the suggested data format for the stream. On output, this contains the accepted data format. The streamer may make some changes to the data format including the data type, sample rate, and channel count. It is strongly suggested that the input format be accepted since that will result in the least amount of processing overhead. The format, channels, frameRate, and bitsPerSample members must be valid upon return. If the streamer changes the data format, only PCM data formats are acceptable.
Returns: true if the data format is accepted by the streamer.
Returns: false if the streamer can neither handle the requested format nor can it change the requested format to something it likes.

inline virtual StreamState writeData(const void *data, size_t bytes) override

writes a buffer of data to the stream.

Remark

This writes a buffer of data to the streamer. The streamer is responsible for doing something useful with the audio data (ie: write it to a file, write it to a memory buffer, stream it to another voice, etc). The caller of this function is not interested in whether the streamer successfully does something with the data - it is always assumed that the operation is successful.

Note

This must execute as quickly as possible. If this call takes too long to return and the output is going to a real audio device (through the streamer or some other means), an audible audio dropout could occur. If the audio context is executing in non-realtime mode (ie: baking audio data), this may take as long as it needs only at the expense of making the overall baking process take longer.

Note

This should not be called directly. This will be called by the audio processing engine when a buffer of new data is produced.

Parameters

data – [in] the audio data being written to the streamer. This data will be in the format that was decided on in the call to open() during the context creation or the last call to setOutput(). This buffer will not persist upon return. The implementation must copy the contents of the buffer if it still needs to access the data later.
bytes – [in] the number of bytes of valid data in the buffer data.

Return values

StreamState::eNormal – if the data was written successfully to the streamer and the data production rate should continue at the current rate.
StreamState::eMore – if the data was written successfully to the streamer and the data production rate should be temporarily increased.
StreamState::eLess – if the data was written successfully to the streamer and the data production rate should be temporarily reduced.
StreamState::eCritical – if the data was written successfully to the streamer and more data needs to be provided as soon as possible.
StreamState::eMuchLess – if the data was written successfully to the streamer and the data rate needs to be halved.

inline virtual void close() override

closes the stream.

Remark

This signals that a stream has been finished. This occurs when the engine is stopped or the audio context is destroyed. No more calls to writeData() should be expected until the streamer is opened again.

Note

This should not be called directly. This will be called by the audio processing engine when audio processing engine is stopped or the context is destroyed.

Returns: no return value.

inline void setStreamState(StreamState state)

sets the stream state that will be returned from writeData().

Parameters: state – [in] the stream state to return from each writeData() call. This will affect the behavior of the audio processing engine and its rate of running new cycles. The default is StreamState::eNormal.
Returns: no return value.

inline void acquire()

acquires a single reference to this streamer object.

Remark

This acquires a new reference to this streamer object. The reference must be released later with release() when it is no longer needed. Each call to acquire() on an object must be balanced with a call to release(). When a new streamer object is created, it should be given a reference count of 1.

Returns: no return value.

inline void release()

releases a single reference to this streamer object.

Remark

This releases a single reference to this streamer object. If the reference count reaches zero, the object will be destroyed. The caller should assume the object to have been destroyed unless it is well known that other local references still exist.

Returns: no return value.

template<class Rep, class Period> inline bool waitForClose(const std::chrono::duration<Rep, Period> &duration) noexcept

Wait until the close() call has been given.

Remark

If you disconnect a streamer via IAudioPlayback::setOutput(), the engine may not be stopped, so the streamer won’t be immediately disconnected. In cases like this, you should call waitForClose() if you need to access the streamer’s written data but don’t have access to the close() call (e.g. if you’re using an OutputStreamer).

Parameters: duration – [in] The duration to wait before timing out.
Returns: true if the close call has been given
Returns: false if the timeout was reached.

Public Members

void (*acquireReference)(Streamer *self)

acquires a single reference to a Streamer object.

Remark

This acquires a new reference to a Streamer object. The reference must be released later with releaseReference() when it is no longer needed. Each call to acquireReference() on an object must be balanced with a call to releaseReference(). When a new streamer object is created, it should be given a reference count of 1.

Param self: [in] the object to take the reference of.
Return: no return value.

void (*releaseReference)(Streamer *self)

releases a single reference to a Streamer object.

Remark

This releases a single reference to a Streamer object. If the reference count reaches zero, the object will be destroyed.

Param self: [in] the object to release a reference to. The object may be destroyed if it was the last reference that was released. The caller should consider the object invalid upon return unless it is known that additional local references still exist on it.
Return: no return value.

bool (*openStream)(Streamer *self, SoundFormat *format)

sets the suggested format for the stream output.

Remark

This sets the data format that the streamer will receive its data in. The streamer may change the data format to another valid PCM data format if needed. Note that if the streamer returns a data format that cannot be converted to by the processing engine, the initialization of the output will fail. Also note that if the streamer changes the data format, this will incur a small performance penalty to convert the data to the new format.

Remark

This will be called when the audio context is first created. Once the format is accepted by both the audio context and the streamer, it will remain constant as long as the processing engine is still running on that context. When the engine is stopped (or the context is destroyed), a Streamer::close() call will be performed signaling the end of the stream. If the engine is restarted again, another open() call will be performed to signal the start of a new stream.

Param self: [in] the streamer object to open the stream for. This will not be nullptr.
Param format: [inout] on input, this contains the suggested data format for the stream. On output, this contains the accepted data format. The streamer may make some changes to the data format including the data type, sample rate, and channel count. It is strongly suggested that the input format be accepted since that will result in the least amount of processing overhead. The format, channels, frameRate, and bitsPerSample members must be valid upon return. If the streamer changes the data format, only PCM data formats are acceptable.
Return: true if the data format is accepted by the streamer.
Return: false if the streamer can neither handle the requested format nor can it change the requested format to something it likes.

StreamState (*writeStreamData)(Streamer *self, const void *data, size_t bytes)

writes a buffer of data to the stream.

Remark

This writes a buffer of data to the streamer. The streamer is responsible for doing something useful with the audio data (ie: write it to a file, write it to a memory buffer, stream it to another voice, etc). The caller of this function is not interested in whether the streamer successfully does something with the data - it is always assumed that the operation is successful.

Note

This must execute as quickly as possible. If this call takes too long to return and the output is going to a real audio device (through the streamer or some other means), an audible audio dropout could occur. If the audio context is executing in non-realtime mode (ie: baking audio data), this may take as long as it needs only at the expense of making the overall baking process take longer.

Param self: [in] the streamer object to write a buffer of data into. This will not be nullptr.
Param data: [in] the audio data being written to the streamer. This data will be in the format that was decided on in the call to open() during the context creation or the last call to setOutput(). This buffer will not persist upon return. The implementation must copy the contents of the buffer if it still needs to access the data later.
Param bytes: [in] the number of bytes of valid data in the buffer data.
Retval StreamState::eNormal: if the data was written successfully to the streamer and the data production rate should continue at the current rate.
Retval StreamState::eMore: if the data was written successfully to the streamer and the data production rate should be temporarily increased.
Retval StreamState::eLess: if the data was written successfully to the streamer and the data production rate should be temporarily reduced.

void (*closeStream)(Streamer *self)

closes the stream.

Remark

This signals that a stream has been finished. This occurs when the engine is stopped or the audio context is destroyed. No more calls to writeData() should be expected until the streamer is opened again.

Param self: [in] the streamer object to close the stream for. This will not be nullptr.
Return: no return value.

Protected Functions

inline ~NullStreamer() override

Protected Attributes

StreamState m_state = StreamState::eNormal : the stream state to be returned from each writeData() call.