Loading Hierarchies from .X

Not to beat a dead horse (why would I do a horrible thing like that?), but I want to quickly review how to load a frame hierarchy from an .X file.

For your frame hierarchy you should use the D3DXFRAME structure (or the D3DXFRAME_EX structure). As I mentioned earlier in this chapter, the D3DXFRAME structure (or the derived D3DXFRAME_EX structure) contains two pointers that you use to create the frame hierarchy−pFrameSibling and pFrameFirstChild. Your job is to link each frame you load from an .X file using those two pointers.

Starting with a root frame object, begin iterating every data object from an .X file you specify. When you encounter a Frame object, link it either as a sibling or a child of the previous frame. Continue through the .X file until you have loaded all frames. For this example, use the D3DXFRAME_EX structure to contain the frames in the hierarchy.

Basically, you'll open an .X file for access, and then iterate every data object in the file. For each Frame object you find, you need to create a matching D3DXFRAME (or D3DXFRAME_EX) object and link it to a hierarchy of frames.

To process an .X file, you can construct a class to handle the majority of the work for you. You simply instance the class's ParseObject function, which gives you access to each data object's data.

For now, take a look at the ParseObject function that is called for each data object that is enumerated.

BOOL cXFrameParser::ParseObject(
	IDirectXFileData *pDataObj,
	IDirectXFileData *pParentDataObj,
	DWORD Depth,
	void **Data, BOOL Reference)
{
	const GUID *Type = GetObjectGUID(pDataObj);

	// If the object type is a Frame (non−referenced), then add that frame to the hierarchy.
	if(*Type == TID_D3DRMFrame && Reference == FALSE) 
	{
		// Allocate a frame container
		D3DXFRAME_EX *pFrame = new D3DXFRAME_EX();

		// Get the frame's name (if any)
		pFrame−>Name = GetObjectName(pDataObj);

		// Link frame into hierarchy
		if(Data == NULL) 
		{
			// Link as sibling of root
			pFrame−>pFrameSibling = m_RootFrame;
			m_RootFrame = pFrame; pFrame = NULL;
			Data = (void**)&m_RootFrame;
		} 
		else 
		{
			// Link as child of supplied frame
			D3DXFRAME_EX *pFramePtr = (D3DXFRAME_EX*)*Data;
			pFrame−>pFrameSibling = pFramePtr−>pFrameFirstChild;
			pFramePtr−>pFrameFirstChild = pFrame; pFrame = NULL;
			Data = (void**)&pFramePtr−>pFrameFirstChild;
		}
	}

	// Load a frame transformation matrix
	if(*Type==TID_D3DRMFrameTransformMatrix && Reference==FALSE) 
	{
		D3DXFRAME_EX *Frame = (D3DXFRAME_EX*)*Data;

		if(Frame) 
		{
			Frame−>TransformationMatrix = *(D3DXMATRIX*) GetObjectData(pDataObj, NULL);
			Frame−>matOriginal = Frame−>TransformationMatrix;
		}
	}

	// Parse child objects
	return ParseChildObjects(pDataObj, Depth, Data, Reference);
}

Basically, the ParseObject function is called for each data object that is enumerated. Inside the ParseObject function, you check the currently enumerated object's type (using the object's template GUID). If that type is a Frame, then you allocate a frame structure and load the frame's name into it.

Next, you link the frame into the hierarchy of frames, which is where things look a little strange. The cXFrameParser class maintains two pointers−one for the root frame object that is being built up (m_RootFrame, a member of the class), and one for a data object (Data) that is passed to each call of ParseObject. The data pointer keeps track of the last frame data object that was loaded.

As you begin parsing the .X file, the data pointer Data is set to NULL, meaning that it doesn't point to any frame object being loaded. When you load a frame object into a frame structure, you are checking that data pointer to see whether it points to another frame structure. If it doesn't, it is assumed that the current frame is a sibling of the root. If the data pointer does point to another frame, it is assumed that the currently enumerated frame is a child of the frame to which the data pointer points.

Knowing whether the currently enumerated frame is a sibling or a child is a factor when you are creating the hierarchy. Sibling frames are linked to each other using the pFrameSibling pointer of the D3DXFRAME structure, whereas child frames are linked using pFrameFirstChild. Once a frame has been loaded, the data pointer is adjusted to point at the new frame or back to the sibling frame. In the end, all frames become linked either as siblings or children.

One more thing that you'll notice in the ParseObject function is the code to load a frame's transformation matrix (represented by the FrameTransformMatrix template). A FrameTransformMatrix object is typically embedded in a Frame data object. This FrameTransformMatrix object defines the initial orientation of the Frame being loaded.

For skeletal animation, this frame transformation matrix defines the initial pose of your skeletal structure. For example, a standard skeletal structure might be posed with the body standing erect and the arms extended. However, suppose all of your animations are based on the character standing in a different pose, perhaps with his arms dropped down to his sides and with his legs slightly bent. Instead of reorienting all the vertices or bones to match that pose before saving the .X file in your 3D modeling program, you can change the frame transformations. From that point forward, all motions of the bones will be relative to that pose. This becomes more apparent as you try to manipulate the bone orientations and during animation, so I'll leave the topic alone for the moment. Just know that inside each frame structure you are loading, there is space to store an initial transformation matrix (in the D3DXFRAME::TransformationMatrix object).

After all is said and done, your frame hierarchy will be loaded. Of course, the root frame is stored in the m_RootFrame linked list of D3DXFRAME_EX objects inside the frame−loading class. It's your job to grab that pointer and assign it to one you'll use in your program. After you've done that, you can start messing around with the orientation of the bones.