IDirectDrawSurface7::SetPrivateData
The IDirectDrawSurface7::SetPrivateData method 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 is automatically freed, as appropriate.
- DDSPD_IUNKNOWNPOINTER
- The data at lpData is a pointer to an IUnknown interface. DirectDraw automatically calls the IUnknown::AddRef method of this interface. When this data is no longer needed, DirectDraw automatically calls the IUnknown::Release method of this interface.
- DDSPD_VOLATILE
- The buffer at lpData is only valid while the surface remains unchanged. If the surface's contents change, subsequent calls to the IDirectDrawSurface7::GetPrivateData method return DDERR_EXPIRED.
Return Values
If the method succeeds, the return value is DD_OK.
If it fails, the method can return one of the following error values:
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.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 98.
Header: Declared in ddraw.h.
See Also
IDirectDrawSurface7::GetPrivateData, IDirectDrawSurface7::FreePrivateData