IDirect3DRMObject2

Applications use the methods of the IDirect3DRMObject2 interface to work with the object2 superclass of Microsoft® Direct3D® Retained Mode objects. Microsoft DirectX version 6.0 introduced the IDirect3DRMObject2 interface which all Retained Mode objects implement. Use QueryInterface on any Direct3D Retained Mode object to obtain a pointer to this interface.

IDirect3DRMObject2 implements the following methods which are equivalent to the IDirect3DRMObject methods of the same name:

AddDestroyCallback

Clone

DeleteDestroyCallback

GetName

SetName

Besides the methods IDirect3DRMObject2 shares with IDirect3DRMObject, it implements the following methods.

GetDirect3DRM

GetClientData

GetAge

SetClientData

IDirect3DRMObject2::GetClientData and IDirect3DRMObject2::SetClientData provide data association with an object, which is more flexible than the older IDirect3DRMObject::GetAppData and IDirect3DRMObject::SetAppData methods.

For a conceptual overview of the older object interface, see IDirect3DRMObject. For a history of the Direct3D Retained Mode interfaces, see Interface Changes.

The methods of the IDirect3DRMObject2 interface can be organized into the following groups:

Application-specific data GetClientData
SetClientData
Cloning Clone
Naming GetName
SetName

Miscellaneous GetAge
GetDirect3DRM

Notifications AddDestroyCallback
DeleteDestroyCallback

The IDirect3DRMObject2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

AddRef
QueryInterface
Release

The Direct3DRMObject2 object is obtained through the appropriate call to the QueryInterface method from any Retained Mode object. All Retained Mode objects inherit the IDirect3DRMObject2 interface methods.

IDirect3DRMObject2::AddDestroyCallback

IDirect3DRMObject2

Registers a function that will be called when an object is destroyed.

Syntax

HRESULT AddDestroyCallback(
  D3DRMOBJECTCALLBACK lpCallback,
  LPVOID lpArg
  );

Parameters

lpCallback
User-defined callback function that will be used when the object is destroyed.
lpArg
Address of application-defined data passed to the callback function. Because this function is used after the object has been destroyed, you should not use this function with the object as an argument.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is equivalent to the IDirect3DRMObject method of the same name.

IDirect3DRMObject2::Clone

IDirect3DRMObject2

Creates a copy of an object.

Syntax

HRESULT Clone(
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID *ppvObj
  );

Parameters

pUnkOuter
Pointer to the outer IUnknown interface that allows COM aggregation features.
riid
Identifier of the object being copied.
ppvObj
Address that will contain the copy of the object when the method returns.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObject2::DeleteDestroyCallback

IDirect3DRMObject2

Removes a function previously registered with the IDirect3DRMObject2::AddDestroyCallback method.

Syntax

HRESULT DeleteDestroyCallback(
  D3DRMOBJECTCALLBACK d3drmObjProc,
  LPVOID lpArg
  );

Parameters

d3drmObjProc
User-defined D3DRMOBJECTCALLBACK callback function that will be used when the object is destroyed.
lpArg
Address of application-defined data passed to the callback function.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is equivalent to the IDirect3DRMObject method of the same name.

IDirect3DRMObject2::GetAge

IDirect3DRMObject2

Reports the current age of the object.

Syntax

HRESULT GetAge(
  DWORD dwFlags,
  LPDWORD lpdwAge);

Parameters

dwFlags

Flag value. Must be zero if the object is not a meshbuilder. If the object is a meshbuilder, can be one of the following values.

Default (0)

The meshbuilder ages normally (aging is caused by any change to the meshbuilder).

D3DRMMESHBUILDERAGE_GEOMETRY

The meshbuilder ages whenever the mesh geometry is changed (for example, addition of vertices, faces, or another meshbuilder).

D3DRMMESHBUILDERAGE_MATERIALS

The meshbuilder ages whenever a material-related property of the mesh changes, or when faces or another mesh are added.

D3DRMMESHBUILDERAGE_TEXTURES

The meshbuilder ages whenever a texture-related property of the mesh changes, or when faces or another mesh are added.

lpdwAge

Pointer that receives the age.

Return Value

Returns one of the following values.

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

The age increases when the object is modified.
This method was introduced in DirectX version 6.0. Aging is only supported in DirectX 6.0 and later by the following objects.

Direct3DRMDevice3

Direct3DRMTexture3

Direct3DRMMeshBuilder3

Direct3DRMUserVisual

Direct3DRMShadow2

Direct3DRMWrap

IDirect3DRMObject2::GetClientData

IDirect3DRMObject2

Retrieves the data previously associated with an object through a call to SetClientData.

Syntax

HRESULT GetClientData(  
  DWORD dwID,
  LPVOID *lplpvData);

Parameters

dwID

An application ID obtained from a call to RegisterClient.

lplpvData

Address of a variable that receives the associated data. A NULL value indicates that no data has been set.

Return Value

Returns one of the following values.

D3DRMERR_CLIENTNOTREGISTERED

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTFOUND

DDERR_NOTINITIALIZED

DD_OK

Remarks

If the data is of type IUnknown, this method increments the reference count before returning the data to the caller. This method was introduced in DirectX version 6.0.

IDirect3DRMObject2::GetDirect3DRM

IDirect3DRMObject2

Retrieves a pointer to an interface of the ultimate Direct3DRM object involved in the creation of this object.

Syntax

HRESULT GetDirect3DRM(  
  LPLPDIRECT3DRM lplpD3DRM);

Parameters

lplpD3DRM

Address that receives a pointer to an interface of the ultimate Direct3D Retained Mode object involved in the creation of the object specified by lpDirect3DRMObject.

Return Value

Returns one of the following values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMObject2::GetName

IDirect3DRMObject2

Retrieves the object's name.

Syntax

HRESULT GetName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

Parameters

lpdwSize
Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.
lpName
Address of a variable that will contain a null-terminated string identifying the object's name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObject2::SetClientData

IDirect3DRMObject2

Associates an item of data with a Retained Mode object.

Syntax

HRESULT SetClientData(  
  DWORD dwID,
  LPVOID lpvData,
  DWORD dwFlags);

Parameters

dwID

Application ID obtained from a call to IDirect3DRM3::RegisterClient.

lpvData

Application-specific data to be associated with the object.

dwFlags

Flags that determine how the data is interpreted by Retained Mode.

Flag D3DRMCLIENTDATA_NONE D3DRMCLIENTDATA_LOCALFREE D3DRMCLIENTDATA_IUNKNOWN

Interpretation of data No interpretation Data has been allocated by client; Direct3DRM should free it upon disassociation Data is assumed to point to an IUnknown interface

Behavior on SetClientData No behavior No behavior Direct3D Retained Mode increments the reference count on the interface

Behavior on GetClientData No behavior No behavior Direct3D Retained Mode increments the reference count on the interface before passing it to the caller

Behavior when data is disassociated from the object No behavior Win32 LocalFree function is used on data Direct3D Retained Mode decrements the reference count on the interface

Return Value

Returns one of the following values:

D3DRMERR_CLIENTNOTREGISTERED

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DD_OK

Remarks

The data can be removed by means of a call to this method with NULL as the lpvData parameter, or destruction of the object, or by using IDirect3DRM3::UnregisterClient. If you have previously associated data with the object using the ID specified by dwID, then the previous data is released. The method of destruction depends on the flags passed to this method in the dwFlags parameter. The data can be retrieved by means of a call to GetClientData. This method was introduced in DirectX version 6.0.

IDirect3DRMObject2::SetName

IDirect3DRMObject2

Sets the object's name.

Syntax

HRESULT SetName(
  const char  *lpName
  );

Parameters

lpName
User-defined data to name the object.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is equivalent to the IDirect3DRMObject method of the same name.

Application-specific data	GetClientData
	SetClientData

Cloning	Clone

Naming	GetName
	SetName

Miscellaneous	GetAge
	GetDirect3DRM

Notifications	AddDestroyCallback
	DeleteDestroyCallback

Flag	D3DRMCLIENTDATA_NONE	D3DRMCLIENTDATA_LOCALFREE	D3DRMCLIENTDATA_IUNKNOWN
Interpretation of data	No interpretation	Data has been allocated by client; Direct3DRM should free it upon disassociation	Data is assumed to point to an IUnknown interface
Behavior on SetClientData	No behavior	No behavior	Direct3D Retained Mode increments the reference count on the interface
Behavior on GetClientData	No behavior	No behavior	Direct3D Retained Mode increments the reference count on the interface before passing it to the caller
Behavior when data is disassociated from the object	No behavior	Win32 LocalFree function is used on data	Direct3D Retained Mode decrements the reference count on the interface