IDirect3DRMObject
Applications use the methods of the IDirect3DRMObject interface to work with the object superclass of Microsoft® Direct3D® Retained Mode objects.
Direct3DRMObject is the common superclass of all objects in the system. A Direct3DRMObject object has characteristics common to all objects.
Each Direct3DRMObject object is instantiated as a COM object. In addition to the methods of the IUnknown interface, each object has a standard set of methods that are generic to all.
To create an object, the application must first have instantiated a Direct3D Retained Mode object by calling the Direct3DRMCreate function. The application then calls the method of the object's interface that creates an object, and it specifies parameters specific to the object. For example, to create a Direct3DRMAnimation object, the application would call the IDirect3DRM3::CreateAnimation method. The creation method then creates a new object, initializes some of the object's attributes from data passed in the parameters (leaving all others with their default values), and returns the object. Applications can then specify the interface for this object to modify and use the object.
Any object can store 32 bits of application-specific data. This data is not interpreted or altered by Retained Mode. The application can read this data by using the IDirect3DRMObject::GetAppData method, and it can write to it by using the IDirect3DRMObject::SetAppData method. Finding this data is simpler if the application keeps a structure for each Direct3DRMFrame object. For example, if calling the IDirect3DRMFrame3::GetParent method retrieves a Direct3DRMFrame object, the application can easily retrieve the data by using a pointer to its private structure, possibly avoiding a time-consuming search.
You might also want to assign a name to an object to help you organize an application or as part of your application's user interface. You can use the IDirect3DRMObject::SetName and IDirect3DRMObject::GetName methods to set and retrieve object names.
Another example of possible uses for application-specific data is when an application needs to group the faces within a mesh into subsets (for example, for front and back faces). You could use the application data in the face to note in which of these groups a face should be included.
An application can specify a function to call when an object is destroyed, such as when the application needs to deallocate memory associated with the object. To do this, use the IDirect3DRMObject::AddDestroyCallback method. To remove a function previously registered with this method, use the IDirect3DRMObject::DeleteDestroyCallback method.
The callback function is called only when the object is destroyed—that is, when the object's reference count has reached 0 and the system is about to deallocate the memory for the object. If an application kept additional data about an object (so that its dynamics could be implemented, for example), the application could use this callback function as a way to notify itself that it can dispose of the data.
For information about grouping objects, see IDirect3DRMObjectArray.
The methods of the IDirect3DRMObject interface can be organized into the following groups:
| Application-specific | GetAppData |
| data | SetAppData |
| Cloning | Clone |
| Naming | GetClassName |
| GetName | |
| SetName | |
| Notifications | AddDestroyCallback |
| DeleteDestroyCallback |
The IDirect3DRMObject 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 Direct3DRMObject object is obtained through the appropriate call to the QueryInterface method from any Retained Mode object. All Retained Mode objects inherit the IDirect3DRMObject interface methods.
IDirect3DRMObject::AddDestroyCallback
IDirect3DRMObject
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.
IDirect3DRMObject::Clone
IDirect3DRMObject
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.
IDirect3DRMObject::DeleteDestroyCallback
IDirect3DRMObject
Removes a function previously registered with the IDirect3DRMObject::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.
IDirect3DRMObject::GetAppData
IDirect3DRMObject
Retrieves the 32 bits of application-specific data in the object. The default value of the data is 0.
Syntax
DWORD GetAppData( );
Return Value
Returns the data value defined by the application.
See Also
IDirect3DRMObject::GetClassName
IDirect3DRMObject
Retrieves the name of the object's class.
Syntax
HRESULT GetClassName(
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 class 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.
IDirect3DRMObject::GetName
IDirect3DRMObject
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.
See Also
IDirect3DRMObject::SetAppData
IDirect3DRMObject
Sets the 32 bits of application-specific data in the object.
Syntax
HRESULT SetAppData(
DWORD ulData
);
Parameters
- ulData
- User-defined data to be stored with 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.
See Also
IDirect3DRMObject::SetName
IDirect3DRMObject
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.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.