IDirectDrawSurface5::AddAttachedSurface

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDirectDrawSurface5::AddAttachedSurfacemethod attaches the specified surface to this surface.

HRESULT AddAttachedSurface(
LPDIRECTDRAWSURFACE4
lpDDSAttachedSurface
);

Parameters

lpDDSAttachedSurface

Address of an IDirectDrawSurface5interface 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:

DDERR_CANNOTATTACHSURFACE

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACEALREADYATTACHED

DDERR_SURFACELOST

DDERR_WASSTILLDRAWING

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::DeleteAttachedSurfacemethod. 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 AddAttachedSurfaceor DeleteAttachedSurfaceon 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

Runs on	Versions	Declared in	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	ddraw.h	ddraw.lib