IDirectDrawSurface3::GetAttachedSurface

The IDirectDrawSurface3::GetAttachedSurface method obtains the attached surface that has the specified capabilities.

HRESULT GetAttachedSurface(
  LPDDSCAPS lpDDSCaps,                             
  LPDIRECTDRAWSURFACE3 FAR *lplpDDAttachedSurface  
);

Parameters

lpDDSCaps
Address of a DDSCAPS structure that contains the hardware capabilities of the surface.
lplpDDAttachedSurface
Address of a variable that will contain a pointer to the retrieved surface's IDirectDrawSurface3 interface. The retrieved surface is the one that matches the description according to the lpDDSCaps parameter.

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_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

Remarks

Attachments are used to connect multiple DirectDrawSurface objects into complex structures, like the ones needed to support 3-D page flipping with z-buffers. This method fails if more than one surface is attached that matches the capabilities requested. In this case, the application must use the IDirectDrawSurface3::EnumAttachedSurfaces method to obtain the attached surfaces.

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.