IDirectDrawSurface5::SetPrivateData

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::SetPrivateDatamethod associates data with the surface that is intended for use by the application, not by DirectDraw. Data is passed by value, and multiple sets of data can be associated with a single surface.

HRESULT SetPrivateData(
REFGUID
guidTag
,
LPVOID
lpData
,
DWORD
cbSize
,
DWORD
dwFlags
);

Parameters

guidTag

Reference to (C++) or address of (C) the globally unique identifier that identifies the private data to be set.

lpData

Address of a buffer that contains the data to be associated with the surface.

cbSize

Size of the buffer at lpData, in bytes.

dwFlags

Flags describing the type of data being passed, or requesting that the data be invalidated when the surface changes. The following flags are defined:

(none)	If no flags are specified, DirectDraw allocates memory to hold the data within the buffer, and copies the data into the new buffer. The buffer allocated by DirectDraw will automatically be freed as appropriate.
DDSPD_IUNKNOWNPOINTER	The data at lpDatais a pointer to an IUnknowninterface. DirectDraw automatically calls the IUnknown::AddRefmethod of this interface. When this data is no longer needed, DirectDraw automatically calls the IUnknown::Releasemethod of this interface.
DDSPD_VOLATILE	The buffer at lpDatais valid while the surface remains unchanged from its current state. If the surface's contents change, subsequent calls to the IDirectDrawSurface5::GetPrivateDatamethod will return DDERR_EXPIRED.

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_OUTOFMEMORY

Remarks

DirectDraw does not manage the memory at lpData. If this buffer was dynamically allocated, it is the caller's responsibility to free the memory.

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