Direct3DRMObject
Applications use the methods of the Direct3DRMObject 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.
To create an object, the application must first have instantiated a Direct3D Retained Mode object. 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 Direct3DRM3.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 Direct3DRMObject.GetAppData method, and it can write to it by using the Direct3DRMObject.SetAppData method. Finding this data is simpler if the application keeps a structure for each Direct3DRMFrame object. For example, if calling the Direct3DRMFrame3.GetParent method retrieves a Direct3DRMFrame object, the application can easily retrieve the data by accessing 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 Direct3DRMObject.SetName and Direct3DRMObject.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 method 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 Direct3DRMObject.AddDestroyCallback method. To remove a function previously registered with this method, use the Direct3DRMObject.DeleteDestroyCallback method.
The callback is called only when the object is destroyed 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 as a way to notify itself that it can dispose of the data.
The methods of the Direct3DRMObject interface can be organized into the following groups.
Application-specific data GetAppData SetAppData Cloning CloneObject Naming GetClassName GetName SetName Notifications AddDestroyCallback DeleteDestroyCallback
All Retained Mode objects inherit the Direct3DRMObject interface methods.
Direct3DRMObject.AddDestroyCallback
Direct3DRMObject
Registers a function that will be called when an object is destroyed.
This method is not implemented.
Syntax
object.AddDestroyCallback(fn As Direct3DRMCallback, arg As Variant)
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
- fn
- User-defined Direct3DRMCallback callback interface that will be used when the object is destroyed.
- arg
- Application-defined data passed to the callback. Because this function is used after the object has been destroyed, you should not use this function with the object as an argument.
Error Values
This method returns E_NOTIMPL.
Direct3DRMObject.CloneObject
Direct3DRMObject
Creates a copy of an object.
Syntax
object.CloneObject( ) As Direct3DRMObject
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
Return Value
Returns a copy of the object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMObject.DeleteDestroyCallback
Direct3DRMObject
Removes a function previously registered with the Direct3DRMObject.AddDestroyCallback method.
This method is not implemented.
Syntax
object.DeleteDestroyCallback(fn As Direct3DRMCallback, args As Variant)
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
- fn
- User-defined Direct3DRMCallback interface that will be used when the object is destroyed.
- args
- Application-defined data passed to the callback.
Error Values
This method returns E_NOTIMPL.
Direct3DRMObject.GetAppData
Direct3DRMObject
Retrieves the 32 bits of application-specific data in the object. The default value of the data is 0.
Syntax
object.GetAppData( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
Return Value
Returns the data value defined by the application.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMObject.GetClassName
Direct3DRMObject
Retrieves the name of the object's class.
Syntax
object.GetClassName( ) As String
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
Return Value
Returns a string identifying the class name.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Direct3DRMObject.GetName
Direct3DRMObject
Retrieves the object's name.
Syntax
object.GetName( ) As String
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
Return Value
Returns a string identifying the object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMObject.SetAppData
Direct3DRMObject
Sets the 32 bits of application-specific data in the object.
Syntax
object.SetAppData(data As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
- data
- User-defined data to be stored with the object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Direct3DRMObject.SetName
Direct3DRMObject
Sets the object's name.
Syntax
object.SetName(name As String)
Parts
- object
- Object expression that resolves to a Direct3DRMObject object.
- name
- User-defined string to name the object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.