Private Surface Data

You can store any kind of application-specific data with a surface. For example, a surface representing a map in a game might contain information about terrain.

A surface can have more than one private data buffer. Each buffer is identified by a GUID which you supply when attaching the data to the surface.

To store private surface data, you use the IDirectDrawSurface5::SetPrivateData method, passing in a pointer to the source buffer, the size of the data, and an application-defined GUID for the data. Setting the DDSPD_VOLATILE flag indicates that the data being attached to the surface is valid only as long as the contents of the surface do not change. (See Surface Uniqueness Values.)

SetPrivateData allocates an internal buffer for the data and copies it. You can then safely free the source buffer or object. The internal buffer or interface reference is released when IDirectDrawSurface5::FreePrivateData is called. This happens automatically when the surface is freed.

To retrieve private data for a surface, you must allocate a buffer of the correct size and then call the IDirectDrawSurface5::GetPrivateData method, passing the GUID that was assigned to the data by SetPrivateData. You are responsible for freeing any dynamic memory you use for this buffer.

If you do not know how big a buffer to allocate, first call GetPrivateData with zero in *lpcbBufferSize. If the method fails with DDERR_MOREDATA, it returns the necessary number of bytes in *lpcbBufferSize.

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.