IDirectDrawSurface::GetAttachedSurface

HRESULT GetAttachedSurface(LPDDSCAPS lpDDSCaps,

LPLPDIRECTDRAWSURFACE FAR * lplpDDAttachedSurface);

Obtains the attached surface that has the specified capabilities.

·Returns DD_OK if successful, or one of the following error values otherwise:

lpDDSCaps

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

lplpDDAttachedSurface

Address of a pointer to a DirectDrawSurface that will be attached to the current DirectDrawSurface specified by lpDDSurface and has capabilities that match those specified by the lpDDSCaps parameter.

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