Index
|
|
|
|
|
| |||
| |||
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:
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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.