## Direct3D Retained Mode Architecture

This section gives an overview of the Microsoft® Direct3D® Retained Mode interfaces. 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.
- Z-Buffers in Retained Mode describes how Direct3D Retained Mode handles overlays.

### 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
Direct3DRMAnimation | Defines how a transformation will be modified—often in reference to a Direct3DRMFrame or Direct3DRMFrame2 object. You can use it to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.
Direct3DRMAnimationSet | Allows Direct3DRMAnimation objects to be grouped together.
Direct3DRMDevice | Represents the visual display destination for the renderer.
Direct3DRMDevice2 | Represents the visual display destination for the renderer. Same as the Direct3DRMDevice object but with enhanced control of transparency.
Direct3DRMFace | Represents a single polygon in a mesh.
Direct3DRMFrame | Positions objects within a scene and defines the positions and orientations of visual objects.
Direct3DRMFrame2 | Extends the Direct3DRMFrame object by enabling access to the frame axes, bounding boxes, and materials. Also supports ray picking.
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.
Direct3DRMMaterial | Defines how a surface reflects light.
Direct3DRMMesh | Consists of a set of polygonal faces. You can use this object to manipulate groups of faces and vertices.
Direct3DRMMeshBuilder | Allows you to work with individual vertices and faces in a mesh.
Direct3DRMMeshBuilder2 | Allows you to work with individual vertices and faces in a mesh. Same as the Direct3DRMMeshBuilder object but with than the Direct3DRMMeshBuilder object.
Direct3DRMObject | Used as a base class by all other Direct3D Retained Mode objects. It has characteristics that are common to all objects.
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.
Direct3DRMShadow | Defines a shadow.
Direct3DRMTexture | Represents a rectangular array of colored pixels.
Direct3DRMTexture2 | Represents 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.
Direct3DRMUserVisual | Provides functionality not otherwise available in the system. It is defined by an application.
Direct3DRMViewport | Defines how the 3-D scene is rendered into a 2-D window.
Direct3DRMVisual | Represents 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 IDirect3DRM Array Interfaces.

### 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 IDirect3DRMDevice::QueryInterface method to retrieve the IDirect3DRMWinDevice interface, but not to retrieve the IDirect3DRMVisual interface.

Object name | Supported interfaces
Direct3DRMAnimation | IDirect3DRMAnimation
Direct3DRMAnimationSet | IDirect3DRMAnimationSet
Direct3DRMDevice | IDirect3DRMDevice, IDirect3DRMWinDevice
Direct3DRMDevice2 | IDirect3DRMDevice2, IDirect3DRMWinDevice
Direct3DRMFace | IDirect3DRMFace
Direct3DRMFrame | IDirect3DRMFrame, IDirect3DRMVisual
Direct3DRMFrame2 | IDirect3DRMFrame2, IDirect3DRMVisual
Direct3DRMInterpolator | IDirect3DRInterpolator
Direct3DRMLight | IDirect3DRMLight
Direct3DRMMaterial | IDirect3DRMMaterial
Direct3DRMMesh | IDirect3DRMMesh, IDirect3DRMVisual
Direct3DRMMeshBuilder | IDirect3DRMMeshBuilder, IDirect3DRMVisual
Direct3DRMMeshBuilder2 | IDirect3DRMMeshBuilder2, IDirect3DRMVisual
Direct3DRMProgressiveMesh | IDirect3DRMProgressiveMesh, IDirect3DRMVisual
Direct3DRMShadow | IDirect3DRMShadow, IDirect3DRMVisual
Direct3DRMTexture | IDirect3DRMTexture, IDirect3DRMTexture2, IDirect3DRMVisual
Direct3DRMUserVisual | IDirect3DRMUserVisual, IDirect3DRMVisual
Direct3DRMViewport | IDirect3DRMViewport
Direct3DRMWrap | IDirect3DRMWrap

The following example illustrates how to create two interfaces to a single Direct3DRMDevice object. The IDirect3DRM::CreateObject method creates an uninitialized Direct3DRMDevice object. The IDirect3DRMDevice::InitFromClipper method initializes the object. The call to the IDirect3DRMDevice::QueryInterface method creates a second interface to the Direct3DRMDevice object—an IDirect3DRMWinDevice interface that the application will use to handle WM_PAINT and WM_ACTIVATE messages.

    d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,
        IID_IDirect3DRMDevice,(LPVOID FAR*)&dev1);
    dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice,
        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 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 IDirect3DRM::CreateObject method; instead, they should use the creation methods listed below for each interface:

Array interface | Creation method
IDirect3DRMDeviceArray | IDirect3DRM::GetDevices
IDirect3DRMFaceArray | IDirect3DRMMeshBuilder::GetFaces or IDirect3DRMMeshBuilder2::GetFaces
IDirect3DRMFrameArray | IDirect3DRMPickedArray::GetPick, IDirect3DRMPicked2Array::GetPick, or IDirect3DRMFrame::GetChildren
IDirect3DRMLightArray | IDirect3DRMFrame::GetLights
IDirect3DRMObjectArray | IDirect3DRMInterpolator::GetAttachedObjects
IDirect3DRMPickedArray | IDirect3DRMViewport::Pick
IDirect3DRMPicked2Array | IDirect3DRMFrame2::RayPick
IDirect3DRMViewportArray | IDirect3DRM::CreateFrame
IDirect3DRMVisualArray | IDirect3DRMFrame::GetVisuals

### Objects and Reference Counting

When an object is created, its reference count is increased. Each time an application creates a child of an object or a method returns a pointer to an object, the system increases the reference count for that object. The object is not deleted until its reference count reaches zero.

Applications need to keep track of the reference count for a single object only—the root of the scene. The system keeps track of the other reference counts automatically. Applications should be able to simply release the scene, the viewport, and the device when they clean up before exiting. (When your application releases the viewport, the system automatically takes care of the camera's references.) Theoretically, an application could release a viewport without releasing the device (if it needed to add a new viewport to the device, for example), but when an application releases a device, it should release the viewport as well.

The reference count of a child or visual object increases when it is added to a frame. When you use the IDirect3DRMFrame::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.

### Z-Buffers in Retained Mode

The order in the z-buffer determines the order in which overlays clip each other. Overlays are assumed to be on top of all other screen components. Overlays that do not have a specified z-order behave in unpredictable ways when overlaying the same area on the primary surface. Direct3D Retained Mode does not sort overlays if you do not have a z-buffer. Overlays without a specified z-order are assumed to have a z-order of 0, and will appear in the order they are rendered. The possible z-order of overlays ranges from 0, which is just on top of the primary surface, to 4 billion, which is as close to the viewer as possible. An overlay with a z-order of 2 would obscure an overlay with a z-order of 1. No two overlays can have the same z-order.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.