IDirect3DResource9::SetPrivateData method (d3d9helper.h)

Article
02/22/2024

Associates data with the resource that is intended for use by the application, not by Direct3D. Data is passed by value, and multiple sets of data can be associated with a single resource.

Syntax

HRESULT SetPrivateData(
  [in] REFGUID    refguid,
  [in] const void *pData,
  [in] DWORD      SizeOfData,
  [in] DWORD      Flags
);

Parameters

[in] refguid

Type: REFGUID

Reference to the globally unique identifier that identifies the private data to set.

[in] pData

Type: const void*

Pointer to a buffer that contains the data to be associated with the resource.

[in] SizeOfData

Type: DWORD

Size of the buffer at pData, in bytes.

[in] Flags

Type: DWORD

Value that describes the type of data being passed, or indicates to the application that the data should be invalidated when the resource changes.

Item	Description
(none)	If no flags are specified, Direct3D allocates memory to hold the data within the buffer and copies the data into the new buffer. The buffer allocated by Direct3D is automatically freed, as appropriate.
D3DSPD_IUNKNOWN	The data at pData is a pointer to an IUnknown interface. SizeOfData must be set to the size of a pointer to IUnknown, that is, sizeof(IUnknown). Direct3D automatically callsIUnknown through pData when the private data is destroyed. Private data will be destroyed by a subsequent call to IDirect3DResource9::SetPrivateData* with the same GUID, a subsequent call to IDirect3DResource9::FreePrivateData, or when the IDirect3D9 object is released. For more information, see Remarks.

Item

Description

(none)

If no flags are specified, Direct3D allocates memory to hold the data within the buffer and copies the data into the new buffer. The buffer allocated by Direct3D is automatically freed, as appropriate.

D3DSPD_IUNKNOWN

The data at pData is a pointer to an IUnknown interface. SizeOfData must be set to the size of a pointer to IUnknown, that is, sizeof(IUnknown*). Direct3D automatically callsIUnknown through pData when the private data is destroyed. Private data will be destroyed by a subsequent call to IDirect3DResource9::SetPrivateData with the same GUID, a subsequent call to IDirect3DResource9::FreePrivateData, or when the IDirect3D9 object is released. For more information, see Remarks.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. If the method fails, the return value can be one of the following: D3DERR_INVALIDCALL, E_OUTOFMEMORY.

Remarks

Direct3D does not manage the memory at pData. If this buffer was dynamically allocated, it is the calling application's responsibility to free the memory.

Requirements

Requirement	Value
Target Platform	Windows
Header	d3d9helper.h (include D3D9.h)
Library	D3D9.lib