 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. |
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::SetPrivateDatamethod, passing in a pointer to the source buffer, the size of the data, and an application-defined GUID for the data. Optionally, the source data can exist in the form of a COM object; in this case, you pass a pointer to the object's IUnknowninterface pointer and you set the DDSPD_IUNKNOWNPOINTER flag. Another flag, DDSPD_VOLATILE, 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.)
SetPrivateDataallocates 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::FreePrivateDatais 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::GetPrivateDatamethod, 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 the data is a COM object, this method retrieves the IUnknownpointer.
If you don't know how big a buffer to allocate, first call GetPrivateDatawith zero in * lpcbBufferSize.If the method fails with DDERR_MOREDATA, it returns the necessary number of bytes in *lpcbBufferSize.
Last updated on Tuesday, May 18, 2004