What's New in Direct3D Retained Mode?

This section discusses new features and documentation in Microsoft® Direct3D® Retained Mode version 6.0.

Microsoft Visual Basic programmers should consult the Visual Basic Reference for information on how to use Direct3D Retained Mode.

This article contains the following sections.

• New Articles
• New Interfaces

New Articles

Most of the Getting Started section is new and contains the following articles.

• Documentation Roadmap outlines where to go in this documentation for information on particular topics.
• Rotating an Object: The RMBegin1 Sample contains a walkthrough of a simple sample that rotates an object.
• Frame Hierarchies: The RMBegin2 Sample contains a walkthrough of a simple sample that provides a sun, planet, and moon scenario with each object revolving around the other appropriate objects.
• How to Enumerate Devices contains a walkthrough of a sample that enumerates devices.
• Eliminating Redundant State Changes explains how to avoid setting the state to a value equal to its current value, which can help performance.

The Samples section of this documentation is new. You can reach the section through Direct3D Retained Mode Samples Introduction, which leads to the following new articles.

• Building Samples Using Developer Studio 5.0
• Direct3D Retained Mode Samples

Direct3D Retained Mode Overviews contains the following new articles.

• Interface Hierarchy Chart
• Interface Changes

New Interfaces

Microsoft® Direct3D® Retained Mode version 6.0 introduces several interfaces and a number of other interfaces that add new methods, and thereby new functionality, to old interfaces. For a complete list of the new interfaces and methods, see Interface Changes. For information about interface inheritance see the new Interface Hierarchy Chart.

This documentation covers the latest version of an interface and notes differences between versions rather than duplicating information. For example, where you would have previously found separate, but nearly identical documentation for IDirect3DRMTexture3::GetDecalSize, IDirect3DRMTexture2::GetDecalSize, and IDirect3DRMTexture::GetDecalSize you will now find that method documented under the latest version of that interface as IDirect3DRMTexture3::GetDecalSize.

The Reference contains the following new interfaces.

• Retained Mode version 6.0 introduces a new IDirect3DRM3 interface and Direct3DRM3 object. MeshBuilder3 objects created using IDirect3DRM3 use the DirectX Immediate Mode DrawPrimitive interface. Lights created with IDirect3DRM3 take advantage of new Immediate Mode functionality and use the Immediate Mode D3DLIGHT2 structure. IDirect3DRM3 provides all the functionality of IDirect3DRM2 and IDirect3DRM. It adds a flag parameter to CreateDeviceFromSurface, allowing you to indicate that no z-buffer should be created, and adds the RegisterClient and UnregisterClient methods. IDirect3DRM3 also adds the GetOptions and SetOptions methods to set and retrieve whether left-handed or right-handed geometry should be used.

• All objects implement the new IDirect3DRMObject2 interface. IDirect3DRMObject2, unlike the other new interfaces, does not implement all the methods of its predecessor. IDirect3DRMObject2 and IDirect3DRMObject continue to be documented separately. IDirect3DRMObject2 adds the SetClientData and GetClientData methods that work in conjunction with the new IDirect3DRM3::RegisterClient and IDirect3DRM3::UnregisterClient methods. It also adds the GetDirect3DRM and GetAge methods.

• IDirect3DRMAnimation2 adds the AddKey, DeleteKeyByID, GetKeys, and ModifyKey methods that allow access to the keys of an animation. It also adds the GetFrame method that returns the frame of the corresponding animation.

• The new IDirect3DRMAnimationArray interface lets you retrieve the number of animations in the array using GetSize and request the interface for an animation using GetElement.

• IDirect3DRMAnimationSet2 adds the GetAnimations method that enables you to retrieve the constituent animations.

• The new IDirect3DRMClippedVisual interface allows you to clip visuals against arbitrary planes before rendering. New ClippedVisual objects are created from the Direct3DRM3 object.

• IDirect3DRMDevice3 adds the FindPreferredTextureFormat method to select a texture format based on certain criteria. IDirect3DRMDevice3 also introduces several methods that can be used to eliminate redundant state changes: GetStateChangeOptions, LightStateChange, RenderStateChange, and SetStateChangeOptions.

• IDirect3DRMFace2 adds a SetTexture method with which you can specify textures whose height and width are not a power a two.

• IDirect3DRMFrame3 provides methods that enable additional transformation capabilities between model- and world-space, retrieving the world 4x4 transform, setting and retrieving traversal options, and setting and retrieving whether fogging is done through vertex fog or table fog. It also provides methods for setting and retrieving material overrides. The SetOrientation method now respects scale and shear.

• IDirect3DRMMaterial2 adds the GetAmbient and SetAmbient methods to allow finer control over material properties.

• IDirect3DRMMeshBuilder3 adds methods to delete face, normal, and vertex objects. It also adds the Empty and Optimize methods. Other new IDirect3DRMMeshBuilder3 methods retrieve one or more normals, the number of normals, the texture topology, faces, one or more vertices, and the state (enabled or disabled) of the meshbuilder. This interface enables you to set vertices and normals and to create and retrieve new sub-meshes and parent meshes of the meshbuilder. IDirect3DRMMeshBuilder3 also enables the application to add new triangles and to implicitly create new faces by using the AddTriangles method.

• IDirect3DRMShadow2 adds methods allowing the visual, light, plane, and option shadow parameters to be changed after creation. SetOptions allows you to set an option that eliminates visual artifacts when blended transparency is enabled.

• IDirect3DRMTexture3 extends the Changed method by allowing you to specify the changed region of the texture. It also provides the texture management caching methods GetCacheOptions and SetCacheOptions. GetSurface, SetDownSampleCallback, and SetValidationCallback are the other new methods IDirect3DRMTexture3 provides.

• IDirect3DRMViewport2 adds a flag parameter to Clear, indicating whether the target surface, z-buffer surface, or dirty rectangle list are cleared.

---

 Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.