Directsound Learning Guide for collaboration level

Collaboration level

Because Windows is a multi-task environment, multiple applications may operate on a device drive at any time. Although collaboration levels are used, DirectX ensures that each application cannot access the device in the wrong way or at the wrong time. Each DirectSound application has a collaboration level to determine the degree to which it is allowed to access devices.
　
After creating a device object, you must use the IDirectSound8: SetCooperativeLevel method to set the collaboration level for the device. If you do not do this, you will not be able to hear the sound. The following example sets the collaboration level for the DirectSound device, which is identified by the IDirectSound8 interface lpDirectSound. The Hwnd parameter is the application window handle.

HRESULT hr = lpDirectSound-> SetCooperativeLevel (hwnd, DSSCL_PRIORITY ); If (FAILED (hr )) ...{ ErrorHandler (hr); // Add error-handling here. }

DirectSound defines three levels of collaboration for sound devices, which are specified by DSSCL_NORMAL, DSSCL_PRIORITY, and DSSCL_WRITEPRIMARY.

Note: The DSSCL_EXCLUSIBE collaboration level is outdated. A DirectX application can no longer silence other applications. Applications requiring a dedicated level will be given priority.

　　Standard collaboration level

Under the standard collaboration level (DSSCL_NORMAL), the application cannot set the format of the primary buffer, fill the primary buffer, or compress the On-board memory of the device. All applications at this collaboration level use a master buffer in 22 KHz, stereo sound, and 8-bit sampling format, so that devices can switch smoothly between applications.

　　Priority collaboration level

When a DirectSound device is used out of the priority level (DSSCL_PRIORITY), the application enjoys priority over hardware resources, such as hardware mixing, and sets the format of the primary buffer, and compresses the On-board memory of the device.

Game programs should use a priority level of collaboration in almost all environments. This level gives the application the most powerful behavior ability to control the sampling rate and bit depth. The priority level of collaboration also allows voice from other applications (such as IP Phones) to be heard together with the voice in the game.

　　Write master buffer collaboration level

The highest level of collaboration is the write master buffer (DSSCL_WRITEPRIMARY ). When using this cooperative level DirectSound device, your application can directly access the primary buffer of a non-WDM driver. In this mode, the application must directly fill the primary buffer. At this time, the secondary buffer cannot be played.

An application must be set to the primary buffer level to obtain direct write access to audio samples in the primary buffer zone. If the application is not set to this level, all calls to the IDirectSoundBuffer: Lock method on the primary buffer will fail.

Note: The primary buffer only supports the IDirectSoundBuffer interface, rather than IDirectSoundBuffer8.

When your application is set to write master buffer collaboration level and out of the foreground location, all secondary buffers used for other applications will be stopped and marked as lost. When your application is successively moved to the background, its primary buffer is marked as lost and restored when the application moves to the foreground again.

If a DirectSound drive is not in the user system, you cannot set the write master buffer collaboration level. To determine whether this is the case, call the IDirectSound8: GetCaps method and check the DSCAPS_EMULDRIVER ID in the DSCAPS structure.