IDirectDrawSurface5::SetPrivateData

This 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 table shows the possible flags.

  Flag	Description
  (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_VOLATILE	The buffer at lpData is valid while the surface remains unchanged from its current state. If the surface's contents change, subsequent calls to the IDirectDrawSurface5::GetPrivateData method 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:

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

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::GetPrivateData | IDirectDrawSurface5::FreePrivateData

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.