carb::audio::DeviceCaps

struct DeviceCaps

contains information about a single audio input or output device.

This information can be retrieved with IAudioPlayback::getDeviceCaps() or IAudioCapture::getDeviceCaps(). Note that this information should not be stored since it can change at any time due to user activity (ie: unplugging a device, plugging in a new device, changing system default devices, etc). Device information should only be queried just before deciding which device to select.

Public Members

size_t thisSize = sizeof(DeviceCaps)

indicates the size of this object to allow for versioning and future expansion.

This must be set to sizeof(DeviceCaps) before calling getDeviceCaps().

size_t index

the current index of this device in the enumeration order.

Note that this value is highly volatile and can change at any time due to user action (ie: plugging in or removing a device from the system). When a device is added to or removed from the system, the information for the device at this index may change. It is the caller’s responsibility to refresh its collected device information if the device list changes. The device at index 0 will always be considered the system’s ‘default’ device.

DeviceFlags flags

flags to indicate some attributes about this device.

These may change at any time due to user action (ie: unplugging a device or switching system defaults). This may be 0 or any combination of the fDeviceFlag* flags.

char name[kMaxNameLength]

a UTF-8 string that describes the name of the audio device.

This will most often be a ‘friendly’ name for the device that is suitable for display to the user. This cannot be guaranteed for all devices or platforms since its contents are defined by the device driver. The string will always be null terminated and may have been truncated if it was too long.

carb::extras::Guid guid

a GUID that can be used to uniquely identify the device.

The GUID for a given device may not be the same from one process to the next, or if the device is removed from the system and reattached. The GUID will remain constant for the entire time the device is connected to the system however.

size_t channels

the preferred number of channels of data in each frame of the audio data.

Selecting a device using a different format than this will result in extra processing overhead due to the format conversion.

size_t frameRate

the preferred number of frames per second that must be played back for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).

Selecting a device using a different frame rate than this will result in extra processing overhead due to the frame rate conversion.

SampleFormat format = SampleFormat::eDefault 

the preferred format of each sample of audio data.

This is given as a symbolic name so that the data can be interpreted properly. Selecting a device using a different format than this will result in extra processing overhead due to the format conversion.