Testing Cooperative Levels

Developers often use messages such as WM_ACTIVATEAPP and WM_DISPLAYCHANGE as notifications that their applications should restore or re-create the surfaces being used. In some cases, applications take action when they don't need to, or don't take action when they should. The IDirectDraw7::TestCooperativeLevel method in C++ or the corresponding DirectDraw7.TestCooperativeLevel method in Visual Basic makes it possible for your application to retrieve more information about the DirectDraw object's cooperative level and take appropriate steps to continue execution without mishap.

The TestCooperativeLevel method succeeds, returning DD_OK, if your application can restore its surfaces (if it has not already done so) and continue to execute. Failure codes, on the other hand, are interpreted differently depending on the cooperative-level your application uses:

Full-screen applications

Full-screen applications receive the DDERR_NOEXCLUSIVEMODE return value if they lose exclusive device access–for example, if the user pressed ALT+TAB to switch away from the current application. In this case, applications might call TestCooperativeLevel in a loop, exiting only when the method returns DD_OK (meaning that exclusive mode was returned). In the body of the loop, the application should relinquish control of the CPU to prevent using cycles unnecessarily. Windows supports functions such as the WaitMessage or Sleep Win32 functions for this purpose.

Any existing surfaces should be restored by calling the IDirectDrawSurface7::Restore or IDirectDraw7::RestoreAllSurfaces methods in C++ or DirectDrawSurface7.Restore in Visual Basic, and their contents reloaded before displaying them.

Windowed applications

Windowed applications (those that use the normal cooperative level) receive DDERR_EXCLUSIVEMODEALREADYSET if another application has taken exclusive device access. In this case, no action should be taken until the application with exclusive access loses it. This situation is similar to the case for a full-screen application; a windowed application might loop until TestCooperativeLevel returns DD_OK before restoring and reloading its surfaces. As mentioned previously, in a loop like this applications should avoid unnecessarily using CPU cycles by relinquishing CPU control periodically during the loop.

The TestCooperativeLevel method returns DDERR_WRONGMODE to windowed applications when the display mode has changed. In this case, the application should destroy and re-create any surfaces before continuing execution.