Microsoft DirectX 9.0 SDK Update (October 2004)

Mesh.LoadHierarchyFromFile Method

Language:

Note: This documentation is preliminary and is subject to change.

Loads the first frame hierarchy in a DirectX (.x) file.

Definition

Visual Basic .NET Public Shared Function LoadHierarchyFromFile( _
    ByVal filename As String, _
    ByVal options As MeshFlags, _
    ByVal device As Device, _
    ByVal allocHierarchy As AllocateHierarchy, _
    ByVal userDataLoader As LoadUserData _
) As AnimationRootFrame
C# public static AnimationRootFrame LoadHierarchyFromFile(
    string filename,
    MeshFlags options,
    Device device,
    AllocateHierarchy allocHierarchy,
    LoadUserData userDataLoader
);
Managed C++ public: static AnimationRootFrame LoadHierarchyFromFile(
    String *filename,
    MeshFlags options,
    Device *device,
    AllocateHierarchy *allocHierarchy,
    LoadUserData *userDataLoader
);
JScript .NET public static function LoadHierarchyFromFile(
    filename : String,
    options : MeshFlags,
    device : Device,
    allocHierarchy : AllocateHierarchy,
    userDataLoader : LoadUserData
) : AnimationRootFrame;

Parameters

filename System.String. String that specifies the file name.
options Microsoft.DirectX.Direct3D.MeshFlags. One or more flags from the MeshFlags enumeration that specify creation options for the mesh (excepting the Simplify* and Optimize* flags).
device Microsoft.DirectX.Direct3D.Device. A Device object that represents the device associated with the mesh.
allocHierarchy Microsoft.DirectX.Direct3D.AllocateHierarchy. An AllocateHierarchy object. See Remarks.
userDataLoader Microsoft.DirectX.Direct3D.LoadUserData. Application-provided object that allows loading of user data. For more information, see LoadUserData.

Return Value

Microsoft.DirectX.Direct3D.AnimationRootFrame . An AnimationRootFrame. The AnimationRootFrame.AnimationController property contains an AnimationController that corresponds to an animation, created with default tracks and events, in the .x file.

Remarks

All meshes in the file are collapsed into one output mesh. If the file contains a frame hierarchy, all of the transformations are applied to the mesh.

The LoadHierarchyFromFile method loads the animation data and frame hierarchy from a .x file. It scans the .x file and builds a frame hierarchy and animation controller according to the object, derived from AllocateHierarchy, that is passed to it through param_AllocateHierarchy_allocHierarchy. Loading the data requires the following steps.

  1. Derive AllocateHierarchy, implementing each method. This controls how frames and meshes are allocated and freed.
  2. Derive LoadUserData, implementing each method. If the .x file has no embedded user-defined data, or if it is not needed, this step can be skipped.
  3. Create an object of the AllocateHierarchy class, and optionally of the LoadUserData class. You do not need to call any methods of these objects yourself.
  4. Call LoadHierarchyFromFile, passing in the AllocateHierarchy and LoadUserData objects (or null) to create the frame hierarchy and animation controller. All of the animation sets and frames are automatically registered to the animation controller.

During the load, AllocateHierarchy.CreateFrame and LoadUserData.LoadFrameChildData are called back on each frame to control its loading and allocation. The application defines these methods to control how frames are stored.

The AllocateHierarchy.CreateMeshContainer and LoadUserData.LoadMeshChildData methods are called back on each mesh object to control their loading and allocation. The LoadUserData.LoadTopLevelData method is called back for each top-level object that is not loaded by the other methods.

Exceptions
InvalidCallException The method call is invalid. For example, a method's parameter might contain an invalid value.
OutOfMemoryException Leave Site Microsoft® Direct3D® could not allocate sufficient memory to complete the call.


© 2004 Microsoft Corporation. All rights reserved. Terms of use.

Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center