This section describes working with waveform-audio devices, and includes information on how to open, close and query them for their capabilities. It also describes how to keep track of the devices in a system by using device handles and device identifiers.
Use the waveOutOpen function to open a waveform-audio output device for playback. This function opens the device associated with the specified device identifier and returns a handle of the open device by writing the handle of a specified memory location.
Some multimedia computers have multiple waveform-audio output devices. Unless you want to open a specific waveform-audio output device in a system, you should use the WAVE_MAPPER flag for the device identifier when you open a device. The waveOutOpen function chooses the device in the system that is best able to play the specified data format.
Windows provides the following functions to determine how many devices of a certain type are available in a system.
| Function | Description |
|---|---|
| auxGetNumDevs | Retrieves the number of auxiliary output devices present in the system. |
| WaveInGetNumDevs | Retrieves the number of waveform-audio input devices present in the system. |
| WaveOutGetNumDevs | Retrieves the number of waveform-audio output devices present in the system. |
Audio devices are identified by a device identifier. The device identifier is determined implicitly from the number of devices present in a system. Device identifiers range from zero to one less than the number of devices present. For example, if there are two waveform-audio output devices in a system, valid device identifiers are 0 and 1.
After you determine how many devices of a certain type are present in a system, you can use one of the following functions to query the capabilities of each device.
| Function | Description |
|---|---|
| auxGetDevCaps | Retrieves the capabilities of a specified auxiliary output device. |
| waveInGetDevCaps | Retrieves the capabilities of a specified waveform-audio input device. |
| waveOutGetDevCaps | Retrieves the capabilities of a specified waveform-audio output device. |
Each of these functions fills a structure with information about the capabilities of a specified device. The following table lists the structures that correspond to each of these functions.
| Function | Structure |
|---|---|
| auxGetDevCaps | AUXCAPS |
| waveInGetDevCaps | WAVEINCAPS |
| waveOutGetDevCaps | WAVEOUTCAPS |
Standard formats are listed in the dwFormats member of the WAVEOUTCAPS structure. Waveform-audio devices can support nonstandard formats. To determine whether a particular format (standard or nonstandard) is supported by a device, you can call the waveOutOpen function with the WAVE_FORMAT_QUERY flag. This flag does not open the device. You specify the format in question in the WAVEFORMATEX structure pointed to by the pwfx parameter passed to waveOutOpen. For information about setting up this structure, see Devices and Data Types.
Waveform-audio output devices vary in the capabilities they support. The dwSupport member of the WAVEOUTCAPS structure indicates whether a device supports such capabilities as volume and pitch changes.
Each function that opens an audio device specifies a device identifier, a pointer to a memory location, and some parameters that are unique to each type of device. The memory location is filled with a device handle. Use this device handle to identify the open audio device when calling other audio functions.
The difference between identifiers and handles for audio devices is subtle but important:
There are no functions that open or close auxiliary audio devices. Auxiliary audio devices need not be opened and closed like waveform-audio devices because there is no continuous data transfer associated with them. All auxiliary audio functions use device identifiers to identify devices.
The following data types are defined for waveform-audio output functions.
| Type | Description |
|---|---|
| HWAVEOUT | Handle to an open waveform-audio output device. |
| WAVEFORMATEX | Structure that specifies the data formats supported by a particular waveform-audio input device. This structure is also usedfor waveform-audio input devices. |
| WAVEHDR | Structure used as a header for a block of waveform-audio input data. This structure is also used for waveform-audio input devices. |
| WAVEOUTCAPS | Structure used to query the capabilities of a particular waveform-audio output device. |
When you call the waveOutOpen function to open a device driver for playback or to query whether the driver supports a particular data format, use the pwfx parameter to specify a pointer to a WAVEFORMATEX structure containing the requested waveform-audio data format. The WAVEFORMATEX structure is an extended version of the WAVEFORMAT structure. It contains all the members of WAVEFORMAT, and adds two more: a wBitsPerSample member, which contains extra information required for the PCM (Pulse Code Modulation) format, and a cbSize member at the end. You can append data to the structure following cbSize as long as you fill cbSize with the size of the data. You can use the WAVEFORMATEX structure to describe PCM data, although you could also use the PCMWAVEFORMAT structure. When the waveform-audio format type is not PCM, you must use WAVEFORMATEX instead of WAVEFORMAT.
The outmoded WAVEFORMAT structure does not contain all the information required to describe the PCM format. The PCMWAVEFORMAT structure includes a WAVEFORMAT structure along with an additional member containing PCM-specific information. The PCMWAVEFORMAT structure has also been superseded by the WAVEFORMATEX structure.
There are also two clipboard formats you can use to represent audio data: CF_WAVE and CF_RIFF. Use the CF_WAVE format to represent data in one of the standard formats, such as 11 kHz or 22 kHz PCM. Use the CF_RIFF format to represent more complex data formats that cannot be represented as standard waveform-audio files.
After successfully opening a waveform-audio output device driver, you can begin playing a sound. Windows provides the waveOutWrite function for sending data blocks to waveform-audio output devices.
Use the WAVEHDR structure to specify the waveform-audio data block you are sending using waveOutWrite. This structure contains a pointer to a locked data block, the length of the data block, and some flags. This data block must be prepared before you use it; for information about preparing a data block, see Audio Data Blocks.
After you send a data block to an output device by using waveOutWrite, you must wait until the device driver is finished with the data block before freeing it. If you are sending multiple data blocks, you must monitor the completion of data blocks to know when to send additional blocks. For more information about data blocks, see Audio Data Blocks.
The lpData member of the WAVEHDR structure points to the waveform-audio data samples. For 8-bit PCM data, each sample is represented by a single unsigned data byte. For 16-bit PCM data, each sample is represented by a 16-bit signed value. The following table summarizes the maximum, minimum, and midpoint values for PCM waveform-audio data.
| Data format | Maximum value | Minimum value | Midpoint value |
|---|---|---|---|
| 8-bit PCM | 255 (0xFF) | 0 | 128 (0x80) |
| 16-bit PCM | 32,767 (0x7FFF) | – 32,768 (0x8000) | 0 |
The order of the data bytes varies between 8-bit and 16-bit formats and between mono and stereo formats. The following list describes data packing for the different PCM waveform-audio data formats.
| PCM waveform-audio format | Description |
|---|---|
| 8-bit mono | Each sample is 1 byte that corresponds to a single audio channel. Sample 1 is followed by samples 2, 3, 4, and so on. |
| 8-bit stereo | Each sample is 2 bytes. Sample 1 is followed by samples 2, 3, 4, and so on. For each sample, the first byte is channel 0 (the left channel) and the second byte is channel 1 (the right channel). |
| 16-bit mono | Each sample is 2 bytes. Sample 1 is followed by samples 2, 3, 4, and so on. For each sample, the first byte is the low-order byte of channel 0 and the second byte is the high-order byte of channel 0. |
| 16-bit stereo | Each sample is 4 bytes. Sample 1 is followed by samples 2, 3, 4, and so on. For each sample, the first byte is the low-order byte of channel 0 (left channel); the second byte is the high-order byte of channel 0; the third byte is the low-order byte of channel 1 (right channel); and the fourth byte is the high-order byte of channel 1. |
After waveform-audio playback is complete, call waveOutClose to close the output device. If waveOutClose is called while a waveform-audio file is playing, the close operation fails and the function returns an error code indicating that the device was not closed. If you do not want to wait for playback to end before closing the device, call the waveOutReset function before closing. This ends playback and allows the device to be closed. Be sure to use the waveOutUnprepareHeader function to clean up the preparation on all data blocks before closing the device.