| Microsoft DirectX 8.1 (C++) |
A Microsoft® Direct3D® device can be in either an operational state or a lost state. The operational state is the normal state of the device; the device executes and presents all rendering as expected. The device makes a transition to the lost state when an event, such as the loss of keyboard focus in a full-screen application, causes rendering to become impossible. The lost state is characterized by the silent failure of all rendering operations, which means that the rendering methods can return success codes even though the rendering operations fail. In this situation, the error code D3DERR_DEVICELOST is returned by IDirect3DDevice8::Present.
By design, the full set of scenarios that can cause a device to become lost is not specified. Some typical examples include loss of focus, such as when the user presses ALT+TAB or when a system dialog is initialized. Devices can also be lost due to a power management event, or when another application assumes full-screen operation. In addition, any failure from IDirect3DDevice8::Reset puts the device into a lost state.
Note The only methods that are guaranteed to work after a device is lost are IDirect3DDevice8::TestCooperativeLevel, IDirect3DDevice8::Reset, and IUnknown::Release. It is invalid to call any other application programming interfaces (APIs).
If a device is lost, the application queries the device to see if it can be restored to the operational state. If not, the application waits until the device can be restored.
If the device can be restored, the application prepares the device by destroying all video-memory resources and any swap chains. Then, the application calls the IDirect3DDevice8::Reset method. Reset is the only method that has an effect when a device is lost, and is the only method by which an application can change the device from a lost to an operational state. Reset will fail unless the application releases all resources that are allocated in D3DPOOL_DEFAULT, including those created by the IDirect3DDevice8::CreateRenderTarget and IDirect3DDevice8::CreateDepthStencilSurface methods.
For the most part, the high-frequency calls of Direct3D do not return any information about whether the device has been lost. The application can continue to call rendering methods, such as IDirect3DDevice8::DrawPrimitive, without receiving notification of a lost device. Internally, these operations are discarded until the device is reset to the operational state.
The application can determine what to do on encountering a lost device by querying the return value of the IDirect3DDevice8::TestCooperativeLevel method.
In all cases, destroying video-memory resources is a prerequisite to calling Reset, even if the device has not been lost.
Internally, Direct3D does enough work to ensure that a lock operation will succeed after a device is lost. However, it is not guaranteed that the video-memory resource's data will be accurate during the lock operation. It is guaranteed that no error code will be returned. This allows applications to be written without concern for device loss during a lock operation.
Resources can consume video memory. Because a lost device is disconnected from the video memory owned by the adapter, it is not possible to guarantee allocation of video memory when the device is lost. As a result, all resource creation methods are implemented to succeed by returning D3D_OK, but do in fact allocate only dummy system memory. Because any video-memory resource must be destroyed before the device is resized, there is no issue of over-allocating video memory. These dummy surfaces allow lock and copy operations to appear to function normally until the application calls IDirect3DDevice8::Present and discovers that the device has been lost.
All video memory must be released before a device can be reset from a lost state to an operational state. This means that the application should release any swap chains created with IDirect3DDevice8::CreateAdditionalSwapChain and any resources placed in the D3DPOOL_DEFAULT memory class. The application need not release resources in the D3DPOOL_MANAGED or D3DPOOL_SYSTEMMEM memory classes. Other state data is automatically destroyed by the transition to an operational state.
You are encouraged to develop applications with a single code path to respond to device loss. This code path is likely to be similar, if not identical, to the code path taken to initialize the device at startup.
Direct3D allows applications to validate texture and render states against single pass rendering by the hardware using IDirect3DDevice8::ValidateDevice. This method, which is typically invoked during initialization of the application, will return D3DERR_DEVICELOST if the device has been lost.
Direct3D also allows applications to copy generated or previously written images from video-memory resources to nonvolatile system-memory resources. Because the source images of such transfers might be lost at any time, Direct3D allows such copy operations to fail when the device is lost.
The copy operation IDirect3DDevice8::CopyRects can return D3DERR_DEVICELOST when the source object is in volatile memory (D3DPOOL_DEFAULT) and the destination object is in nonvolatile memory (D3DPOOL_SYSTEMMEM or D3DPOOL_MANAGED). Another copy operation, IDirect3DDevice8::GetFrontBuffer, can fail due to retrieving data from the primary surface. Note that these cases are the only instance of D3DERR_DEVICELOST outside of the IDirect3DDevice8::Present, IDirect3DDevice8::TestCooperativeLevel, and IDirect3DDevice8::Reset methods.
In Microsoft® DirectX® 8.1, programmable vertex shaders and programmable pixel shaders don't need to be recreated after Reset. They will be remembered. In previous versions of DirectX, a lost device required shaders to be recreated.