The IDirectDrawSurface3::Restore method restores a surface that has been lost. This occurs when the surface memory associated with the DirectDrawSurface object has been freed.
HRESULT Restore();
Return Values
If the method succeeds, the return value is DD_OK.
If the method fails, the return value may be one of the following error values:
| DDERR_GENERIC |
| DDERR_IMPLICITLYCREATED |
| DDERR_INCOMPATIBLEPRIMARY |
| DDERR_INVALIDOBJECT |
| DDERR_INVALIDPARAMS |
| DDERR_NOEXCLUSIVEMODE |
| DDERR_OUTOFMEMORY |
| DDERR_UNSUPPORTED |
| DDERR_WRONGMODE |
Remarks
This method restores the memory allocated for a surface, but not the contents of that memory. The application is responsible for restoring the contents to reestablish any lost images.
Surfaces can be lost because the mode of the display card was changed or because an application received exclusive access to the display card and freed all of the surface memory currently allocated on the card. When a DirectDrawSurface object loses its surface memory, many methods will return DDERR_SURFACELOST and perform no other function. The IDirectDrawSurface3::Restore method will reallocate surface memory and reattach it to the DirectDrawSurface object.
A single call to this method will restore a DirectDrawSurface object's associated implicit surfaces (back buffers, and so on). An attempt to restore an implicitly created surface will result in an error. IDirectDrawSurface3::Restore will not work across explicit attachments created by using the IDirectDrawSurface3::AddAttachedSurface method ¾ each of these surfaces must be restored individually.
QuickInfo
Windows NT: Use version 5.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.
See Also
IDirectDrawSurface3::IsLost, IDirectDrawSurface3::AddAttachedSurface