天行健 君子當自強而不息

Constructing an .X Parser Class

So, you want to create a class to handle all aspects of parsing .X files, eh? Sounds great to me! In this .X file parser class, you can wrap up the Parse and ParseObject functions you saw earlier in this chapter, in the "Enumerating Data Objects" section. Use the code from those two functions and write the parser class to allow yourself to override the data object parsing functions, which will allow you to scan for specific objects.

Start the parser class with a simple definition and go from there.

class cXParser
{
protected:
	// Function called for every template found
	virtual BOOL ParseObject( 
		IDirectXFileData *pDataObj, 
		IDirectXFileData *pParentDataObj, 
		DWORD Depth, 
		void **Data, BOOL Reference)
	{
		return ParseChildObjects(pDataObj, Depth, Data, Reference);
	}

	// Function called to enumerate child templates
	BOOL ParseChildObjects(IDirectXFileData *pDataObj, DWORD Depth, void **Data, BOOL ForceReference = FALSE);

public:
	// Function to start parsing an .X file
	BOOL Parse(char *Filename, void **Data = NULL);
};

Whoa! I know I said you should start with a simple definition, not what I've just shown here! Bear with me friends, because you'll quickly realize just how simple this class is going to be. So far, you have three functions in your new cXParser .X file parser class. You use these three functions (ParseObject, ParseChildObjects, and Parse) to process a single data object, scan for embedded child objects, and parse an entire file, respectively.

cXParser::Parse, which is the easiest of the functions, merely duplicates the code in the Parse function you used earlier in this chapter.

The second function, ParseObject, is your .X parser's workhorse. ParseObject is called for every single data object found in an .X file. You need to override the ParseObject function (a virtual function) for it to do something useful. As you can see from the ParseObject function prototype, there's a lot going on that'll need some explanation.

The first parameter for ParseObject is an IDirectXFileData object which, as you saw earlier in this chapter, represents the data object that is currently being enumerated. Inside your overridden function, you can access the object's data via the pDataObj pointer.

The second parameter, pParentDataObj (also an IDirectXFileData object), represents the parent (higher−level object) of the current data object that is being enumerated. This is provided in case you want to see whether the current object is a child of another object.

The Depth parameter measures the depth of the object in the hierarchy. The highest−level data objects are at a depth of 0, whereas child objects have their parent's depth plus one. As an example, I have shown a few Frame objects here, with their respective depths listed.

Frame RootFrame { // Depth = 0
  Frame ChildofRoot { // Depth = 1
    Frame ChildofChild { // Depth = 2
    }
  }

  Frame SiblingofRootChild { // Depth = 1
  }
}

Frame RootSibling { // Depth = 0
}

Data is the fourth parameter of ParseObject. It is a user−defined data pointer (or rather, a pointer to a data pointer) that you use to pass information to your parser functions. For example, you can create a data structure to contain all of the information you need.

typedef struct sDATA {
  long NumObjects;
  sDATA() { NumObjects = 0; }
} sDATA:

Note The depth of a data object is extremely useful for sorting hierarchies, such as frame hierarchies used in skeletal animation.

To pass an sDATA structure to your parsing functions, you instance it and use it during a call to cXParser::Parse, as shown here:
sDATA Data;

cXParser Parser;
Parser.Parse("test.x", (void**)&Data);

From then on, every time ParseObject is called you can cast an appropriate pointer to access your data structure.

BOOL cXParser::ParseObject(IDirectXFileData *pDataObj,
  IDirectXFileData *pParentDataObj,
  DWORD Depth,
  void **Data, BOOL Reference)
{
  cDATA *DataPtr = (sDATA*)*Data;
  DataPtr−>NumObjects++; // Increase object count

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

I know I'm getting ahead of myself again by showing you some sample code for cXParser, so let's jump back to the fifth (and last) parameter for ParseObject−Reference. The Reference Boolean variable determines whether the data object being enumerated is referenced or instanced. You can use the Reference variable to determine whether you want to load a referenced object's data or wait for the object to be instanced. This is useful when it comes time to load animation data, which needs data object references rather than actual object instances.

Whew! With the ParseObject function set aside, you're left with the last of the trio of cXParser functions−ParseChildObjects. Thankfully, the ParseChildObjects function is easy−it merely enumerates any child data objects of the object you pass it. Typically, you call ParseChildObjects at the end of your ParseObject function, as I did in the last code bit.

You can see that you need to pass the current IDirectXFileData object, data object depth, data pointer, and reference flag to ParseChildObjects because it is responsible for increasing the depth and setting the parent data object as needed for the next call to ParseObject. If you don't want to parse any child data objects, however, you can skip the call to ParseChildObjects and return a TRUE or FALSE value.(TRUE forces enumeration to continue, whereas FALSE stops it.)

Now that the basics are in place, you need to expand on your parser class a bit. How about adding some functions to retrieve a data object's name, GUID, and data pointer, as well as inserting a couple of functions that are called before and after an .X file is parsed? Take a look at the following code to see what your new parser class should look like.

 

You can see the addition of the BeginParse, EndParse, GetObjectGUID, GetObjectName, and GetObjectData functions in cXParser. You've already seen the code for the three Get functions−it's the virtual BeginParse and EndParse functions that are unknown.

In their current form, both BeginParse and EndParse return TRUE values, which signify a successful function call. It's your job to override these two functions in a derived class so that you can perform any operations prior to and following a file parse. For instance, you might want to initialize any data or provide a data pointer inside your BeginParse function and clean up any used resources inside the EndParse function.

Both the BeginParse and EndParse functions are called directly from the Parse function−you merely need to override them and write the code for them.

As for the three Get functions, you use those by passing a valid IDirectXFileData object; in return, you'll get the name in a newly−allocated data buffer, a pointer to the template's GUID, or a pointer to the object's data buffer and data size value. For example, here's some code that calls the three functions to get and access an object's data:

// pData = pre−loaded data object
char *Name = pParser−>GetObjectName(pData);
const GUID *Type = pParser−>GetObjectGUID(pData);

DWORD Size;
char *Ptr = (char*)pParser−>GetObjectData(pData, &Size);

// Do something with data and free up resource when done
delete [] Name;

As I was saying, using your brand−new cXParser class is going to be really simple.  Advanced readers might want to take it upon themselves to modify the parser class to fit their individual needs. I personally find the class very useful in its current form.

As a quick test of your new cXParser class, let's see just how to derive and use it. Suppose you want to parse .X files for all Mesh data objects and display each one's name in a message box. Here's the code for the parser that will do just that:

class cParser : public cXParser
{
public:
	cParser() { Parse("test.x"); }

	BOOL ParseObject(IDirectXFileData *pDataObj, 
		IDirectXFileData *pParentDataObj, 
		DWORD Depth, 
		void **Data, BOOL Reference)
	{
		if(*GetObjectGUID(pDataObj) == TID_D3DRMMesh) {
			char *Name = GetObjectName(pDataObj);
			MessageBox(NULL, Name, "Mesh template", MB_OK);
			delete [] Name;
		}

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

cParser Parser; // Instancing this will run the parser

Now tell me that wasn't easy! Enough basics, let's get into using .X files for something useful, such as 3D mesh data.