 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
Developers often use messages such as WM_ACTIVATE as notification 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 IDirectDraw4::TestCooperativeLevelmethod 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 TestCooperativeLevelmethod 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 accessfor example, if the user pressed ALT+TAB to switch away from the current application. In this case, applications might call TestCooperativeLevelin 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 WaitMessageor SleepWin32 functions for this purpose.
Any existing surfaces should be restored by calling the IDirectDrawSurface5::Restoreor IDirectDraw4::RestoreAllSurfacesmethods, 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 TestCooperativeLevelreturns 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 TestCooperativeLevelmethod 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.
Last updated on Tuesday, May 18, 2004