IDirectDrawSurface5::SetSurfaceDesc

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.

The IDirectDrawSurface5::SetSurfaceDescmethod sets the characteristics of an existing surface.

HRESULT SetSurfaceDesc(
LPDDSURFACEDESC2
lpddsd2
,
DWORD
dwFlags
);

Parameters

lpddsd2

Address of a DDSURFACEDESC2structure that contains the new surface characteristics.

dwFlags

This parameter is currently not used and must be set to zero.

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

The SetSurfaceDescmethod allows a surface to use data from a previously allocated buffer without copying. You can onlyuse this method to set the surface data and pixel format that is used by an explicit system memory surface. The new surface memory is allocated by the client application and, as such, the client application must also deallocate it.

Using this method incorrectly can cause unpredictable behavior. In particular, the DirectDrawSurfaceobject will not deallocate surface memory that it didn't allocate. Therefore, when the surface memory is no longer needed, be sure to deallocate it. When this method is called, DirectDraw frees the original surface memory that was allocated implicitly when the surface was created.

If your video driver supports allocating system memory surfaces, do not use SetSurfaceDescas some drivers do not respond correctly to this method. Instead, use the IDirectDraw4::CreateSurfacemethod to allocate the surfaces.

Requirements

Runs on	Versions	Declared in	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	ddraw.h	ddraw.lib