| Microsoft DirectX 8.1 (Visual Basic) |
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 that you supply when attaching the data to the surface.
To store private surface data, use the Direct3DSurface8.SetPrivateData method, passing a buffer that contains data to associate with the surface, the size of the data buffer, and an application-defined DXGUID for the data.
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 Direct3DSurface8.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 Direct3DSurface8.GetPrivateData method, passing the DXGUID that was assigned to the data by SetPrivateData. You are responsible for freeing any dynamic memory you use for this buffer.
If you don't know how big a buffer to allocate, first call GetPrivateData with zero in SizeOfData. If the method fails with D3DERR_MOREDATA, it returns the necessary number of bytes for the buffer in SizeOfData.