IDirectDrawSurface5::AddAttachedSurface

This method attaches the specified surface to this surface.

HRESULT AddAttachedSurface( 
  LPDIRECTDRAWSURFACE4 lpDDSAttachedSurface
); 

Parameters

• lpDDSAttachedSurface
  Address of an IDirectDrawSurface5 interface for the surface to be attached.

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:

Remarks

This method increments the reference count of the surface being attached. You can explicitly unattach the surface and decrement its reference count by using the IDirectDrawSurface5::DeleteAttachedSurface method. Unlike complex surfaces that you create with a single call to IDirectDraw4::CreateSurface, surfaces attached with this method are not automatically released. It is the application's responsibility to release such surfaces.

Possible attachments include Z-buffers, alpha channels, and back buffers. Some attachments automatically break other attachments. For example, the 3-D Z-buffer can be attached only to one back buffer at a time. An attachment is not bidirectional, and a surface cannot be attached to itself.

Emulated surfaces (in system memory) cannot be attached to non-emulated surfaces. Unless one surface is a texture map, the two attached surfaces must be the same size.

Using AddAttachedSurface or DeleteAttachedSurface on any surface in a flipping chain is not supported. It may work, but it is likely that memory leaks will result. The functions are primarily provided for future expansion. As a workaround, initially create surfaces in flipping chains with the desired number of buffers.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Ddraw.h.
Link Library: Ddraw.lib.

See Also

IDirectDrawSurface5::EnumAttachedSurfaces

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.