| DirectX SDK |
Because Windows is a multitasking environment, more than one application may be working with a device driver at any one time. Through the use of cooperative levels, DirectX makes sure that each application does not gain access to the device in the wrong way or at the wrong time. Each DirectSound application has a cooperative level that determines the extent to which it is allowed to access the device.
After creating a DirectSound object, you must set the cooperative level for the device with the IDirectSound::SetCooperativeLevel method in C++ or the DirectSound.SetCooperativeLevel method in Visual Basic before you can play sounds.
DirectSound defines four cooperative levels for sound devices: normal, priority, exclusive, and write-primary. These are represented by the values DSSCL_NORMAL, DSSCL_PRIORITY, DSSCL_EXCLUSIVE, and DSSCL_WRITEPRIMARY.
Game applications should use DSSCL_PRIORITY in almost all circumstances. This level gives the most robust behavior while allowing the application control over sampling rate and bit depth. The priority cooperative level also allows audio from other applications (such as IP telephony) to be heard along with the audio from the game. The priority and exclusive levels provide identical performance, so DSSCL_EXCLUSIVE should be used only for applications that require all other applications to be muted. For a music-authoring application, for example, it might be critical that no other audio be heard during playback.
The following C example sets the cooperative level for the DirectSound device initialized at Creating the DirectSound Object. The hwnd parameter is the handle to the application window.
HRESULT hr = lpDirectSound->lpVtbl->SetCooperativeLevel(
lpDirectSound, hwnd, DSSCL_PRIORITY);
The following Visual Basic example sets the cooperative level for the DirectSound device initialized at Creating the DirectSound Object. The hwnd argument is the handle to the application window and DSSCL_PRIORITY, like all flags in the DirectX 7 for Visual Basic type library, is a constant in an enumeration.
m_ds.SetCooperativeLevel Me.hWnd, DSSCL_PRIORITY
At the normal cooperative level, the application cannot set the format of the primary sound buffer, write to the primary buffer, or compact the on-board memory of the device. All applications at this cooperative level use a primary buffer format of 22 kHz, stereo sound, and 8-bit samples, so that the device can switch between applications as smoothly as possible.
When using a DirectSound device with the priority cooperative level, the application has first rights to hardware resources, such as hardware mixing, and can set the format of the primary sound buffer and compact the on-board memory of the device.
At the exclusive cooperative level, the application has all the privileges of the priority level. In addition, when the application is in the foreground, its buffers are the only ones that are audible.
The highest cooperative level is write-primary. When using a DirectSound device with this cooperative level, your application has direct access to the primary sound buffer. In this mode, the application must write directly to the primary buffer. Secondary buffers cannot be played while this is happening.
An application must be set to the write-primary level in order to obtain direct write access to the audio samples in the primary buffer. If the application is not set to this level, then all calls to the IDirectSoundBuffer::Lock method in C++ or DirectSoundBuffer.ReadBuffer and DirectSoundBuffer.WriteBuffer in Visual Basic for the primary buffer will fail.
When your application is set to the write-primary cooperative level and gains the foreground, all secondary buffers for other applications are stopped and marked as lost. When your application in turn moves to the background, its primary buffer is marked as lost and must be restored when the application again moves to the foreground. For more information, see Buffer Management.
You cannot set the write-primary cooperative level if a DirectSound driver is not present on the user's system. To determine whether this is the case, call the IDirectSound::GetCaps method in C++ or DirectSound.GetCaps method in Visual Basic and check for the DSCAPS_EMULDRIVER flag in the DSCAPS structure.
For more information, see Access to the Primary Buffer.