carb::audio::Streamer

struct Streamer

interface for a streamer object.

This gives the audio context a way to write audio data to a generic interface instead of writing the data to an actual audio device. This interface is used by specifying a streamer object in the OutputDesc struct when creating the context or when calling setOutput(). Note that this interface is intended to implement a stateful object with each instance. Two different instances of this interface should be able to operate independently from each other.

There is no requirement for how the incoming audio data is processed. The streamer implementation may do whatever it sees fit with the incoming audio data. Between the any two paired openStream() and closeStream() calls, each writeStreamData() call will be delivering sequential buffers in a single stream of audio data. It is up to the streamer implementation to interpret that audio data and do something useful with it.

Since the internal usage of this streamer object is inherently asynchronous, all streamer objects must be atomically reference counted. When a streamer is set on an audio context, a reference will be taken on it. This reference will be released when the streamer is either removed (ie: a new output target is set for the context), or the context is destroyed.

Note

This interface must be implemented by the host application. No default implementation exists. Some example streamer objects can be found in ‘carb/audio/Streamers.h’.

Subclassed by carb::audio::StreamerWrapper

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.