IDirectDrawSurface3::SetSurfaceDesc

The IDirectDrawSurface3::SetSurfaceDesc method sets the characteristics of an existing surface. This method is new with the IDirectDrawSurface3 interface.

HRESULT IDirectDrawSurface3::SetSurfaceDesc(
  LPDDSURFACEDESC lpddsd,  
  DWORD dwFlags            
);

Parameters

lpddsd: Address of a DDSURFACEDESC structure that contains the new surface characteristics.
dwFlags: This parameter is currently not used and must be set to 0.

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_INVALIDSURFACETYPE

DDERR_INVALIDPIXELFORMAT

DDERR_INVALIDCAPS

DDERR_UNSUPPORTED

DDERR_GENERIC

Remarks

Currently, this method can only be used to set the surface data and pixel format used by an explicit system memory surface. This is useful as it allows a surface to use data from a previously allocated buffer without copying. The new surface memory is allocated by the client application and, as such, the client application must also deallocate it. For more information about how this method is used, see Updating Surface Characteristics.

Using this method incorrectly will cause unpredictable behavior. The DirectDrawSurface object will not deallocate surface memory that it didn't allocate. Therefore, when the surface memory is no longer needed, it is your responsibility to deallocate it. However, when this method is called, DirectDraw frees the original surface memory that it implicitly allocated when creating the surface.

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.