IDirectDrawSurface7::GetAttachedSurface

The IDirectDrawSurface7::GetAttachedSurface method obtains the attached surface that has the specified capabilities and increments the reference count of the retrieved interface.

HRESULT GetAttachedSurface(
  LPDDSCAPS2 lpDDSCaps, 
  LPDIRECTDRAWSURFACE7 FAR *lplpDDAttachedSurface  
);

Parameters

lpDDSCaps

Address of a DDSCAPS2 structure that contains the hardware capabilities of the surface.

lplpDDAttachedSurface

Address of a variable to receive a pointer to the retrieved surface's IDirectDrawSurface7 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 it fails, the method can return one of the following error values:

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 IDirectDrawSurface7::EnumAttachedSurfaces method to obtain the attached surfaces.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 98.
  Header: Declared in ddraw.h.