IDirectDrawSurface4::GetAttachedSurface

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

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

Parameters

lpDDSCaps
Address of a DDSCAPS2 structure that contains the hardware capabilities of the surface.
lplpDDAttachedSurface
Address of a variable that will contain a pointer to the retrieved surface's IDirectDrawSurface4 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 IDirectDrawSurface4::EnumAttachedSurfaces method to obtain the attached surfaces.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in ddraw.h.
  Import Library: Use ddraw.lib.