Mesh.LoadHierarchyFromFile Method

 Language:

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

Definition

Visual Basic 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
);
C++ public:
static AnimationRootFrame LoadHierarchyFromFile(
    String^ filename,
    MeshFlags options,
    Device^ device,
    AllocateHierarchy^ allocHierarchy,
    LoadUserData^ userDataLoader
);
JScript 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.

Send comments about this topic to Microsoft. © Microsoft Corporation. All rights reserved.

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