Loading Frame Hierarchies from .X

Skeletal animation systems require a frame hierarchy (which represents the bone structure) to orient each bone during rendering. The .X file format defines a frame−of−reference data template that you can use to define your bone hierarchy. This template, Frame, is merely a placeholder of sorts. It allows any type of data object to be embedded in it so you can reference the instanced Frame object by its assigned instance name and allow all contained objects to be addressed as well.

Building a frame hierarchy involves parsing an .X file, in which you link each Frame object to another. The relationship is very important−a Frame object can either be a sibling or a child to another Frame object, and it can have an unlimited number of siblings and/or child objects linked to it.

In DirectX 9, you have access to a special DirectX structure called D3DXFRAME to contain each frame in your hierarchy. In this section, you'll use D3DXFRAME to contain a frame hierarchy.

The exact way you parse and build your Frame objects is really up to you. You can use the D3DX library to help, or you can parse/build the hierarchy yourself using your custom .X parser. Which is better for you? Whereas the D3DX library is great to use, I find the methods of using the library to load a frame hierarchy overly complicated, with no less than two interfaces to use and an entire memory−handling class of your own to be written. Why bother when you can load a frame hierarchy using one small .X parser class you created?

Instead, load up your trusty .X parser (which you developed earlier in this chapter, in the "Constructing an .X Parser Class" section) and derive a version that scans for Frame data objects. I'll start you off by showing you the derived class you can use.

class cXFrameParser : public cXParser
{
public:
	// declare an extended version of D3DXFRAME
	// that contains a constructor and destructor
	struct D3DXFRAME_EX : public D3DXFRAME 
	{
		D3DXFRAME_EX()
		{
			Name = NULL;
			pFrameSibling = NULL; pFrameFirstChild = NULL;
		}

		~D3DXFRAME_EX()
		{
			delete [] Name;
			delete pFrameFirstChild;
			delete pFrameSibling;
		}
	} D3DXFRAME_EX;

	// Instance the root frame of the hierarchy
	D3DXFRAME_EX *m_RootFrame;

public:
	cXFrameParser() { m_RootFrame = NULL; }
	~cXFrameParser() { delete m_RootFrame; }

	BOOL BeginParse(void **Data)
	{
		// Clear hierarchy
		delete m_RootFrame; m_RootFrame = NULL;
	}

	BOOL ParseObject(IDirectXFileData *pDataObj, 
		IDirectXFileData *pParentDataObj, 
		DWORD Depth, 
		void **Data, 
		BOOL Reference)
	{
		// Skip reference frames
		if(Reference == TRUE)
			return TRUE;

		// Make sure template being parsed is a frame
		if(*GetObjectGUID(pDataObj) == TID_D3DRMFrame) 
		{
			// Allocate a frame structure
			D3DXFRAME_EX *Frame = new D3DXFRAME_EX();

			// Get frame name (assign one if none found)
			if((Frame−>Name = GetObjectName(pDataObj)) == NULL)
				Frame−>Name = strdup("No Name");

			// Link frame structure into list
			if(Data == NULL) 
			{
				// Link as sibling of root
				Frame−>pFrameSibling = m_RootFrame;
				m_RootFrame = Frame;
				Data = (void**)&m_RootFrame;
			} 
			else 
			{
				// Link as child of supplied frame
				D3DXFRAME_EX *FramePtr = (D3DXFAME_EX*)*Data;
				Frame−>pFrameSibling = FramePtr−>pFrameFirstChild;
				FramePtr−>pFrameFirstChild = Frame;
				Data = (void**)&Frame;
			}
		}

		return ParseChildObjects(pDataObj,Depth,Data,Reference);
	}
};

cXFrameParser Parser;
Parser.Parse("frames.x");

// Parser.m_RootFrame now points to root frame of hierarchy

There you have it. Once the cXFrameParser::Parse function is complete, you'll have a self−contained frame hierarchy ready to use in your project. The ParseFrame demo loads an .X file of your choice and displays the frame hierarchy inside a list box.

ParseFrame Demo

This demo uses the information on loading a frame hierarchy from an .X file. As shown in Figure 3.2, the ParseFrame demo has a button labeled Select .X File. Click that button, locate an .X file to load, and click Open.

Figure 3.2: The ParseFrame demo's dialog box contains two controls−a button you click to load an .X file and a list box that displays the frame hierarchy.

After selecting an .X file to load and clicking Open, you'll be treated to a display of the frame hierarchy contained within the file. To make things easier to understand, the frames are indented by their level in the hierarchy.

Because IDirectXFile interface has been deprecated, I translate this interface into ID3DXFile.

WinMain.cpp:

download source file

Loading Custom Data from .X

As I've expressed throughout this chapter, the .X file format is completely open−ended; there is no limit to the type of data you can store. With that in mind, you can create any type of data storage you want, and accessing that data will be just as easy as accessing the mesh and frame data we've already covered.

Jump back to your ContactEntry template and see just how to parse an .X file and display every instance of ContactEntry. Again, a single small derived class of cXParser will work perfectly here.

#include "initguid.h"

// First declare the ContactEntry GUID
DEFINE_GUID(ContactEntry, \
0x4c9d055b, 0xc64d, 0x4bfe, 0xa7, 0xd9, 0x98, \
0x1f, 0x50, 0x7e, 0x45, 0xff);

// Now, define the .X parser class
class cXContactParser : public cXParser
{
public:
	BOOL ParseObject(IDirectXFileData *pDataObj, 
		IDirectXFileData *pParentDataObj, 
		DWORD Depth, 
		void **Data, 
		BOOL Reference)
	{
		// Skip reference objects
		if(Reference == TRUE)
			return TRUE;

		// Make sure object being parsed is ContactEntry
		if(*GetObjectGUID(pDataObj) == CONTACTENTRY) 
		{
			// Get the data pointer and size
			DWORD DataSize;
			DWORD *DataPtr;

			DataPtr = (DWORD*)GetObjectData(pDataObj, &DataSize);

			// Get name from object data
			char *Name = (char*)*DataPtr++;

			// Get phone # from object data
			char *PhoneNum = (char*)*DataPtr++;

			// Get age from object data
			DWORD Age = *DataPtr++;

			// Display contact information
			char Text[1024];
			sprintf(Text, "Name: %s\r\nPhone #: %s\r\nAge: %lu", Name, PhoneNum, Age);
			MessageBox(NULL, Text, "Contact", MB_OK);
		}

		return ParseChildObjects(pDataObj,Depth,Data,Reference);
	}
};

cXContactParser Parser;
Parser.Parse("contacts.x");

With a single call to cXContactParser::Parse, you're treated to a list of people's names, phone numbers, and ages−all contained in the contacts.x file! Now wasn't that easy? See, you don't have to be afraid of the .X file format. I personally use .X to store as much custom data as I can.