天行健 君子當自強而不息

Retrieving Data from a Data Object

Remember that data objects are containers for data, and if you're going to the trouble to enumerate data objects, it's a safe bet that you're after the data in each one. Once you've got a valid IDirectXFileData object that points at an enumerated data object, you can retrieve the object's instance name, template GUID, and data using a trio of functions. The first function, IDirectXFileData::GetName, retrieves the name of the data object instance.

HRESULT IDirectXFileData::GetName(
  LPSTR pstrNameBuf, // Name buffer
  LPDWORD pdwBufLen); // Size of name buffer

The GetName function takes two parameters−a pointer to a buffer that contains the name and a pointer to a variable that contains the name buffer's size (in bytes). Before you obtain a name from the GetName function, you first have to obtain the name's data size by specifying a NULL value for pstrNameBuf and supplying a value DWORD pointer for pdwBufLen.

// pData = pre−loaded IDirectXFileData object
// Get size of name, in bytes
DWORD Size;
pData−>GetName(NULL, &Size);

Once you've got the size of the name buffer, you can allocate an appropriate buffer and read in the name.

// Allocate name buffer and get name
char *Name = new char[Size];
pData−>GetName(Name, &Size);

While having the data object's instance name helps, you really need the GUID of the object's template to distinguish which template an object uses. To retrieve the GUID of the object's template, you use the IDirectXFileData::GetType function.

HRESULT IDirectXFileData::GetType(const GUID ** ppguid);

With only one parameter to use−a pointer to a const GUID pointer−you can call the GetType function using the following code:

const GUID *TemplateGUID = NULL;
pData−>GetType(&TemplateGUID);

Now that you have the GUID, you can compare it to a list of internal GUIDs (such as those from the standard templates or from your custom templates) and process the data appropriately. For instance, to check whether a data object's type matches that of the MeshNormals standard template, you can use the following code:

// TemplateGUID = template's GUID to check
if(*TemplateGUID == TID_D3DRMMeshNormals) {
  // Process MeshNormals template
}

Of course, knowing the object's template GUID can only get you so far. The real trick is to get at the data object's data. No problem! With one more simple function call at your disposal, your .X file parsing abilities will be nearly complete! The last function you use to access an object's data is GetData.

Retrieves the data for one of the object's members or the data for all members. Deprecated.

HRESULT GetData(
  LPCSTR szMember,
  DWORD * pcbSize,
  void ** ppvData
);

Parameters

szMember

[in] Pointer to the name of the member for which to retrieve data. Specify NULL to retrieve all required members' data.

pcbSize

[out] Pointer to receive the ppvData buffer size, in bytes.

ppvData

[out] Address of a pointer to the buffer to receive the data associated with szMember. If szMember is NULL, ppvData is set to point to a buffer containing all required members' data in a contiguous block of memory.

Return Values

If the method succeeds, the return value is DXFILE_OK. If the method fails, the return value can be one of the following values: DXFILEERR_BADARRAYSIZE, DXFILEERR_BADDataReference, DXFILEERR_BADVALUE.

Remarks

This method retrieves the data for required members of a data object but no data for optional (child) members. Use IDirectXFileData::GetNextObject to retrieve child objects.

To use the GetData function, you need to provide a pointer to access the data object's data buffer and a DWORD variable to contain the buffer's size (in bytes). Here's a snippet of code that shows how you can use GetData to obtain a pointer to the object's data and its size.

char *DataPtr;
DWORD DataSize;
pData−>GetData(NULL, &DataSize, (void**)&DataPtr);

The pointer to the data buffer now points to a block of contiguous memory that is structured just like the data object's template definition. You can access the data as a large buffer or, if you want to be crafty, you can create a structure to match the template's definition for easier access. For example, suppose you have enumerated the ColorRGBA standard template, which is defined as follows:

template ColorRGBA {
  <35FF44E0−6C7C−11cf−8F52−0040333594A3>
  FLOAT red;
  FLOAT green;
  FLOAT blue;
  FLOAT alpha;
}

To access the red, green, blue, and alpha values, you can grab the data pointer and cast it to a float data type.

DWORD DataSize;
float *DataPtr;

pData−>GetData(NULL, &DataSize, (void**)&DataPtr);

float red = *DataPtr++;
float green = *DataPtr++;
float blue = *DataPtr++;
float alpha = *DataPtr++;

While this approach is fine and dandy, you can process the object's data much easier by using a matching C structure.

typedef struct {
  float red, green, blue, alpha;
} sColorRGBA;

sColorRGBA *Color;
DWORD DataSize;
pData−>GetData(NULL, &DataSize, (void**)&Color);

Note Notice that the template's GUID or class name is not part of the data retrieved using IDirectXFileData: :GetData.
Once it is complete, the preceding code gives you the ability to access the colors using the structure instance.

float red = Color−>red;
float blue = Color−>blue;
float green = Color−>green;
float alpha = Color−>alpha;

Accessing single variables is easy, but what about strings and arrays? Arrays, being the easier of the two, are stored contiguously in memory, meaning that you can just increase the memory pointer that contains the object's data. For example, the following code shows you how to access the array of float values stored in a data object of the template type FloatKeys.

// Get the object's data size & pointer
DWORD DataSize;
DWORD *DataPtr;
pData−>GetData(NULL, &DataSize, (void**)&DataPtr);

// The FloatKeys template has a DWORD value 1st that defines how many float values are in the array
DWORD NumKeys = *DataPtr++;

// Next, an array of float values follows
for(DWORD i=0;i<NumKeys;i++) {
  float fValue = *(FLOAT*)DataPtr++;

Accessing arrays wasn't too difficult, so how about accessing strings? Again, it's an easy chore because strings are stored as pointers to a text buffer, which you can access much like I do in the following code. (I'm using the TextureFilename template as an example; it stores the name of a file to use for a texture.)

// Get the data pointer & size
DWORD DataSize;
DWORD *DataPtr;
pData−>GetData(NULL, &DataSize, (void**)&DataPtr);

// Now, access the filename text buffer
char *StringPtr = (char*)*DataPtr;
MessageBox(NULL, StringPtr, "Texture Filename", MB_OK);

With a simple cast to a char pointer, you were able to display the file name contained in the TextureFilename template. Now I know you've got to be banging your forehead and yelling, "Why didn't I see how easy this was before?" Whoa, down boy! I didn't immediately realize just how easy it was to work with .X files either. Now that the secret is out, nothing can stop you from using .X files almost exclusively in your own projects. All you need is a way to wrap up all of this .X parser functionality into a class, making it even easier to work with .X.