Architecture
This section gives an overview of the Microsoft® Direct3D® Retained Mode objects and COM architecture. The following topics are discussed:
- Objects gives a brief description of the Direct3D Retained Mode objects.
- Objects and Interfaces lists the interfaces supported by each object, as well as information on creating interfaces to both single objects and array objects.
- Objects and Reference Counting gives tips on reference counting in Direct3D Retained Mode.
Direct3D Retained Mode Objects
All access to Direct3D Retained Mode is through a small set of objects. The following table lists these objects and a brief description of each:
| Object | Description |
| Direct3DRMAnimation2 | Defines how a transformation will be modified—often in reference to a Direct3DRMFrame3 object. You can use it to animate the position, orientation, and scaling of Direct3DRMVisual, of Direct3DRMLight, and of Direct3DRMViewport2 objects. Same as the Direct3DRMAnimation object, but allows access to the keys and frame of an animation. |
| Direct3DRMAnimationArray | Retrieves the number of animations in the array, and an interface to the requested animation. |
| Direct3DRMAnimationSet2 | Allows Direct3DRMAnimation2 objects to be grouped together. Same as the Direct3DRMAnimationSet object, but allows access to the constituent animations. |
| Direct3DRMClippedVisual | Allows clipping visuals to arbitrary planes before rendering. |
| Direct3DRMDevice3 | Represents the visual display destination for the renderer. Extends the Direct3DRMDevice2 object by enabling you to set and retrieve materials. Direct3DRMDevice2 offers the same functionality as the Direct3DRMDevice object but with enhanced control of transparency. |
| Direct3DRMFace2 | Represents a single polygon in a mesh. |
| Direct3DRMFrame3 | Positions objects within a scene and defines the positions and orientations of visual objects. Extends the Direct3DRMFrame object by enabling access to the frame axes, bounding boxes, and materials. Also supports ray picking. Extends the Direct3DRMFrame2 object by adding to the transform, traversal, and fogging capabilities. |
| Direct3DRMInterpolator | Stores actions and applies the actions to objects with automatic calculation of in-between values. |
| Direct3DRMLight | Defines one of five types of lights that are used to illuminate the visual objects in a scene. |
| Direct3DRMMaterial2 | Defines how a surface reflects light. Same as the Direct3DRMMaterial object, but allows finer control over material properties. |
| Direct3DRMMesh | Consists of a set of polygonal faces. You can use this object to manipulate groups of faces and vertices. |
| Direct3DRMMeshBuilder3 | Allows you to work with individual vertices and faces in a mesh. Extends Direct3DRMMeshBuilder objects by providing more control over normals and allowing retrieval of a face on a mesh. Extends Direct3DRMMeshBuilder2 objects by using the Immediate Mode DrawPrimitive interface when created with the IDirect3DRM3 interface. |
| Direct3DRMObject | Used as a base class by all other Direct3D Retained Mode objects. It has characteristics that are common to all objects. |
| Direct3DRMObject2 | Used as a base class by all other Direct3D Retained Mode objects. It has characteristics that are common to all objects. Enhances Direct3DRMObject by allowing more flexible data association with an object. |
| Direct3DRMPickedArray | Identifies a visual object that corresponds to a given 2-D point. |
| Direct3DRMPicked2Array | Identifies a visual object that corresponds to a given ray intersection. |
| Direct3DRMProgressiveMesh | Consists of a coarse base mesh together with records describing how to incrementally refine the mesh. This allows a generalized level of detail to be set on the mesh, as well as progressive download of the mesh from a remote source. |
| Direct3DRMShadow2 | Defines a shadow. Same as the Direct3DRMShadow object except that shadow properties can be set and retrieved after creation. |
| Direct3DRMTexture3 | Consists of a rectangular array of colored pixels. Same as the Direct3DRMTexture object except that resources can be loaded from files other than the currently executing file, textures can be created from images in memory, and you can generate mipmaps. Enhances the Direct3DRMTexture2 object by allowing finer control over texture management. |
| Direct3DRMUserVisual | Provides functionality not otherwise available in the system. It is defined by an application. |
| Direct3DRMViewport2 | Defines how the 3-D scene is rendered into a 2-D window. Same as the Direct3DRMViewport object except allows you to specify what should be cleared. |
| Direct3DRMVisual | Consists of anything that can be rendered in a scene. Visual objects need not be visible; for example, a frame can be added as a visual object. |
| Direct3DRMWrap | Calculates texture coordinates for a face or mesh. |
Many objects can be grouped into arrays, called array objects. Array objects make it simpler to apply operations to the entire group. The Component Object Model (COM) interfaces that allow you to work with array objects contain the GetElement and GetSize methods. These methods retrieve a pointer to an element in the array and the size of the array, respectively. For more information about array interfaces, see the interface reference section.
Objects and Interfaces
Using the IObjectName::QueryInterface method retrieves a valid interface pointer only if the object supports that interface; therefore, you could use the IDirect3DRMDevice3::QueryInterface method to retrieve the IDirect3DRMWinDevice interface, but not to retrieve the IDirect3DRMVisual interface.
| Object name | Supported interfaces |
| Direct3DRMAnimation2 | IDirect3DRMAnimation2 |
| Direct3DRMAnimationSet2 | IDirect3DRMAnimationSet2 |
| Direct3DRMClippedVisual | IDirect3DRMClippedVisual, IDirect3DRMVisual |
| Direct3DRMDevice3 | IDirect3DRMDevice3, IDirect3DRMWinDevice |
| Direct3DRMFace2 | IDirect3DRMFace2 |
| Direct3DRMFrame3 | IDirect3DRMFrame3, IDirect3DRMVisual |
| Direct3DRMInterpolator | IDirect3DRInterpolator |
| Direct3DRMLight | IDirect3DRMLight |
| Direct3DRMMaterial2 | IDirect3DRMMaterial2 |
| Direct3DRMMesh | IDirect3DRMMesh, IDirect3DRMVisual |
| Direct3DRMMeshBuilder3 | IDirect3DRMMeshBuilder3, IDirect3DRMVisual |
| Direct3DRMProgressiveMesh | IDirect3DRMProgressiveMesh, IDirect3DRMVisual |
| Direct3DRMShadow2 | IDirect3DRMShadow2, IDirect3DRMVisual |
| Direct3DRMTexture3 | IDirect3DRMTexture3, IDirect3DRMVisual |
| Direct3DRMUserVisual | IDirect3DRMUserVisual, IDirect3DRMVisual |
| Direct3DRMViewport2 | IDirect3DRMViewport2 |
| Direct3DRMWrap | IDirect3DRMWrap |
The following example illustrates how to create two interfaces to a single Direct3DRMDevice3 object. The IDirect3DRM3::CreateObject method creates an uninitialized Direct3DRMDevice3 object. The IDirect3DRMDevice3::InitFromClipper method initializes the object. The call to the IDirect3DRMDevice3::QueryInterface method creates a second interface to the Direct3DRMDevice3 object—an IDirect3DRMWinDevice interface that the application will use to handle WM_PAINT and WM_ACTIVATE messages.
d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,
IID_IDirect3DRMDevice3,(LPVOID FAR*)&dev1);
dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice3,
r.right, r.bottom);
dev1->QueryInterface(IID_IDirect3DRMWinDevice, (LPVOID*) &dev2);
To determine whether two interfaces refer to the same object, use the QueryInterface method of each interface, and compare the values of the pointers they return. If the pointer values are the same, the interfaces refer to the same object.
All Direct3D Retained Mode objects support the IDirect3DRMObject, IDirect3DRMObject2 and IUnknown interfaces in addition to the interfaces in the preceding list. Array objects are not derived from IDirect3DRMObject. Array objects have no class identifiers (CLSIDs) because they are not needed. Applications cannot create array objects in a call to the IDirect3DRM3::CreateObject method; instead, they should use the creation methods listed below for each interface:
Objects and Reference Counting
When an object is created, its reference count is incremented. Each time an application creates a child of an object or a method returns a pointer to an object, the system increments the reference count for that object. The object is not deleted until its reference count reaches zero. When you are finished with an object be sure to call the object's Release method to decrement its reference count. For example, you could call IDirect3DRM3::CreateMeshBuilder to create an IDirect3DRMMeshBuilder3 object and IDirect3DRMMeshBuilder3::GetFaces to retrieve an IDirect3DRMFaceArray object. Before your application terminates you should call the Release method on the IDirect3DRMMeshBuilder3 object and also call the Release method on the IDirect3DRMFaceArray object. If you do not call Release, the objects will not be properly released and your application will leak resources. For other examples of when to release objects, see the Direct3D Retained Mode sample code.
In Direct3D Retained Mode there is internal and external reference counting. If you have created or imported objects, such as textures, and applied them to objects in your scene, such as frames or meshes, you can then release your copy of the created or imported object's interface, and when the scene is finished with the object it will be automatically released by D3DRM for you. For example, if you create a meshbuilder object, its reference count is 1. If you then add it to a frame, its reference count is 2. You can then release your copy of the pointer to the meshbuilder object, and the meshbuilder object's reference count will be 1. Then, when you release the scene containing the frame, the reference count of the meshbuilder object will be decremented (to 0) for you and the object will be released. As another example, if you import a texture, the texture object's reference count is 1. If you apply the texture to a mesh, its reference count is 2. You can then release your copy of the pointer to the texture object, and its reference count is 1. When the mesh goes away, the texture object's reference count will be decremented and it will be released as well.
If you always release your objects after they have been applied in the scene, your application does not need to keep track of the reference count for them, but only for the root of the scene. Retained Mode keeps track of the other reference counts automatically. In this case, your application should be able to simply release the scene, the viewport, and the device when it cleans up before exiting. (When your application releases the viewport, the system automatically takes care of the camera's references.)
The reference count of a child or visual object increases when it is added to a frame. When you use the IDirect3DRMFrame3::AddChild method to move a child from one parent to another, the system handles the reference counting automatically.
After your application loads a visual object into a scene, the scene handles the reference counting for the visual object. The application no longer needs the visual object and can release it.
Creating and applying a wrap does not increase the reference count of any objects because wrapping is really just a convenient method of calculating texture coordinates.
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.