D3DXLoadMeshHierarchyFromX function

Loads the first frame hierarchy from a .x file.

Syntax

HRESULT D3DXLoadMeshHierarchyFromX(
  _In_  LPCTSTR                   Filename,
  _In_  DWORD                     MeshOptions,
  _In_  LPDIRECT3DDEVICE9         pDevice,
  _In_  LPD3DXALLOCATEHIERARCHY   pAlloc,
  _In_  LPD3DXLOADUSERDATA        pUserDataLoader,
  _Out_ LPD3DXFRAME               *ppFrameHierarchy,
  _Out_ LPD3DXANIMATIONCONTROLLER *ppAnimController
);

Parameters

Filename [in]

Type: LPCTSTR

Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.

MeshOptions [in]

Type: DWORD

Combination of one or more flags from the D3DXMESH enumeration that specify creation options for the mesh.

pDevice [in]

Type: LPDIRECT3DDEVICE9

Pointer to an IDirect3DDevice9 interface, the device object associated with the mesh.

pAlloc [in]

Type: LPD3DXALLOCATEHIERARCHY

Pointer to an ID3DXAllocateHierarchy interface.

pUserDataLoader [in]

Type: LPD3DXLOADUSERDATA

Application provided interface that allows loading of user data. See ID3DXLoadUserData.

ppFrameHierarchy [out]

Type: LPD3DXFRAME*

Returns a pointer to the loaded frame hierarchy. See D3DXFRAME.

ppAnimController [out]

Type: LPD3DXANIMATIONCONTROLLER*

Returns a pointer to the animation controller corresponding to animation in the .x file. This is created with default tracks and events. See ID3DXAnimationController.

Return value

Type: HRESULT

If the function succeeds, the return value is D3D_OK. If the function fails, the return value can be one of the following values: D3DERR_INVALIDCALL, E_OUTOFMEMORY.

Remarks

The compiler setting also determines the function version. If Unicode is defined, the function call resolves to D3DXLoadMeshHierarchyFromXW. Otherwise, the function call resolves to D3DXLoadMeshHierarchyFromXA.

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

D3DXLoadMeshHierarchyFromX 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 ID3DXAllocateHierarchy-derived object passed to it through pAlloc. Loading the data requires several steps as follows:

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

During the load, CreateFrame and LoadFrameChildData are called back on each frame to control loading and allocation of the frame. The application defines these methods to control how frames are stored. CreateMeshContainer and LoadMeshChildData are called back on each mesh object to control loading and allocation of mesh objects. LoadTopLevelData is called back for each top level object that doesn't get loaded by the other methods.

To free this data, call ID3DXAnimationController::Release to free the animation sets, and D3DXFRAMEDestroy, passing in the root node of the frame hierarchy and an object of your derived ID3DXAllocateHierarchy class. DestroyFrame and DestroyMeshContainer will each be called for every frame and mesh object in the frame hierarchy. Your implementation of DestroyFrame should release everything allocated by CreateFrame, and likewise for the mesh container methods.

Requirements

See also

Animation Functions