carb::audio::OutputDesc

struct OutputDesc

descriptor of the audio output target to use for an audio context.

This may be specified both when creating an audio context and when calling setOutput(). An output may consist of a real audio device or one or more streamers.

Public Members

OutputFlags flags = 0

flags to indicate which output target is to be used.

Currently only a single output target may be specified. This must be one of the fOutputFlag* flags. Future versions may allow for multiple simultaneous outputs. If this is 0, the default output device will be selected. If more than one flag is specified, the audio device index will specify which device to use, and the streamer table will specify the set of streamers to attach to the output.

size_t deviceIndex = 0

the index of the device to open.

This must be greater than or equal to 0 and less than the most recent return value of getDeviceCount(). Set this to 0 to choose the system’s default playback device. This defaults to 0. This value is always ignored if the fOutputFlagDevice flag is not used.

SpeakerMode speakerMode = kSpeakerModeDefault 

the output speaker mode to set.

This is one of the SpeakerMode names or a combination of the fSpeakerFlag* speaker flags. This will determine the channel layout for the final output of the audio engine. This channel layout will be mapped to the selected device’s speaker mode before sending the final output to the device. This may be set to kSpeakerModeDefault to cause the engine’s output to match the output of the device that is eventually opened. This defaults to kSpeakerModeDefault.

size_t frameRate = 0

the frame rate in Hertz to run the processing engine at.

This should be 0 for any output that targets a real hardware device (ie: the fOutputFlagDevice is used in flags or flags is 0), It is possible to specify a non-zero value here when a hardware device is targeted, but that may lead to unexpected results depending on the value given. For example, this could be set to 1000Hz, but the device could run at 48000Hz. This would process the audio data properly, but it would sound awful since the processing data rate is so low. Conversely, if a frame rate of 200000Hz is specified but the device is running at 48000Hz, a lot of CPU processing time will be wasted.

When an output is targeting only a streamer table, this should be set to the frame rate to process audio at. If this is 0, a frame rate of 48000Hz will be used. This value should generally be a common audio processing rate such as 44100Hz, 48000Hz, etc. Other frame rates can be used, but the results may be unexpected if a frame cannot be perfectly aligned to the cycle period.

size_t streamerCount = 0

the number of streams objects in the streamer table.

This value is ignored if the fOutputFlagStreamer flag is not used.

Streamer **streamer = nullptr

a table of one or more streamer objects to send the final output to.

The number of streamers in the table is specified in streamerCount. These streamer objects must be both implemented and instantiated by the caller. The streamers will be opened when the new output target is first setup. All streamers in the table will receive the same input data and format settings when opened. This value is ignored if the fOutputFlagStreamer flag is not used. Each object in this table will be opened when the audio processing engine is started on the context. Each streamer will receive the same data in the same format. Each streamer will be closed when the audio processing engine is stopped or the context is destroyed.

A reference to each streamer will be acquired when they are assigned as an output. These references will all be released when they are no longer active as outputs on the context (ie: replaced as outputs or the context is destroyed). No entries in this table may be nullptr.

Note

If more than one streamer is specified here, It is the caller’s responsibility to ensure all of them will behave well together. This means that none of them should take a substantial amount of time to execute and that they should all return as consistent a stream state as possible from writeStreamData(). Furthermore, if multiple streamers are targeting real audio devices, their implementations should be able to potentially be able to handle large amounts of latency (ie: up to 100ms) since their individual stream state returns may conflict with each other and affect each other’s timings. Ideally, no more than one streamer should target a real audio device to avoid this stream state build-up behavior.

void *ext = nullptr

extended information for this descriptor.

This is reserved for future expansion and should be set to nullptr.