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.