Loading Meshes from .X

Now that you've got a firm grip on how the .X file format works, consider how Microsoft first intended for you to use it−to contain 3D mesh information for your games. The D3DX library comes with a number of functions you can use to load mesh data from an .X file. With the addition of the .X parser developed in this chapter, you have even more options available to you. Check out just how easy it is to work with D3DX to load mesh data.

Loading Meshes Using D3DX

The D3DX library defines the handy ID3DXMesh object that contains and renders 3D meshes for you. Although you can use your own custom mesh storage containers, I find sticking to the ID3DXMesh object perfectly sensible. That's the object I'll use for the rest of this chapter (with the exception of the also−handy ID3DXSkinMesh object, which you'll see in a moment).

The fastest way to load mesh data using D3DX is to call on the D3DXLoadMeshFromX and D3DXLoadMeshFromXof functions. Both of these meshes will take the data contained within an .X file and convert it to an ID3DXMesh object. The D3DXLoadMeshFromX file loads an entire .X file at once (compressing all meshes into a single output mesh), whereas the D3DXLoadMeshFromXof function loads a single mesh pointed at by an IDirectXFileData object.

The D3DXLoadMeshFromX function provides a file name to load, some flags to control loading aspects, a 3D device pointer, pointers to buffers for containing material data, and some miscellaneous data pointers that you can ignore for now.

Loads a mesh from a DirectX .x file.

HRESULT D3DXLoadMeshFromX(
  LPCTSTR pFilename,
  DWORD Options,
  LPDIRECT3DDEVICE9 pD3DDevice,
  LPD3DXBUFFER * ppAdjacency,
  LPD3DXBUFFER * ppMaterials,
  LPD3DXBUFFER * ppEffectInstances,
  DWORD * pNumMaterials,
  LPD3DXMESH * ppMesh
);

Parameters

pFilename

[in] Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.

Options

[in] Combination of one or more flags from the D3DXMESH enumeration, which specifies creation options for the mesh.

pD3DDevice

[in] Pointer to an IDirect3DDevice9 interface, the device object associated with the mesh.

ppAdjacency

[out] Pointer to a buffer that contains adjacency data. The adjacency data contains an array of three DWORDs per face that specify the three neighbors for each face in the mesh. For more information about accessing the buffer, see ID3DXBuffer.

ppMaterials

[out] Pointer to a buffer containing materials data. The buffer contains an array of D3DXMATERIAL structures, containing information from the DirectX file. For more information about accessing the buffer, see ID3DXBuffer.

ppEffectInstances

[out] Pointer to a buffer containing an array of effect instances, one per attribute group in the returned mesh. An effect instance is a particular instance of state information used to initialize an effect. See D3DXEFFECTINSTANCE. For more information about accessing the buffer, see ID3DXBuffer.

pNumMaterials

[out] Pointer to the number of D3DXMATERIAL structures in the ppMaterials array, when the method returns.

ppMesh

[out] Address of a pointer to an ID3DXMesh interface, representing the loaded mesh.

Return Values

If the function succeeds, the return value is D3D_OK. If the function fails, the return value can be one of the following values: D3DERR_INVALIDCALL, E_OUTOFMEMORY.

Remarks

The compiler setting also determines the function version. If Unicode is defined, the function call resolves to D3DXLoadMeshFromXW. Otherwise, the function call resolves to D3DXLoadMeshFromXA because ANSI strings are being used.

All the meshes in the file will be collapsed into one output mesh. If the file contains a frame hierarchy, all the transformations will be applied to the mesh.

For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the D3DMATERIAL9 structure.

The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of "Texture0" with an annotation called "Name." This will contain the string file name for the texture.

First, you need to instance an ID3DXMesh object.

ID3DXMesh *Mesh = NULL;

From there, suppose you want to load the .X file called test.x. Simple enough−you just need to specify the file name in the call to D3DXLoadMeshFromX but wait! What's with the Options parameter? You use it to tell D3DX how to load the mesh−into system memory or video memory, using write−only memory, and so on. A flag represents each option. Table 3.3 lists some of the most common macros.

From Table 3.3, you can see there are really not many options for loading meshes. In fact, I recommend using only D3DXMESH_SYSTEMMEM or D3DXMESH_WRITEONLY The first option, D3DXMESH_SYSTEMMEM, forces your mesh's data to be stored in system memory, making access to the mesh data faster for both read and write operations.

Specifying D3DXMESH_DYNAMIC means you are going to change the mesh data periodically. It's best to specify this flag if you plan to periodically change the mesh's data (such as vertices) in any way during run time.

If speed is your need, then I suggest using the D3DXMESH_WRITEONLY flag, which tells D3DX to use memory that will not allow read access. Most often that means you will use video memory because it is usually (but not always) write−only. If you're not going to read a mesh's vertex data, then I suggest using this flag.

Tip If you're not using system memory or write−only access, what's left to use? Just specify a value of 0 for Options in the call to D3DXLoadMeshFromX, and you'll be fine.

Getting back to the parameters of D3DXLoadMeshFromX, you'll see the pointer to a 3D device interface. No problem−you should have one of those hanging around in your project! Next is the ID3DXBUFFER pointer, ppAdjacency. Set that to NULL−you won't be using it here.

The next three parameters, ppMaterials, ppEffectInstance, and pNumMaterials, contain the mesh's material information, such as material color values and texture file names, as well as effects data. If you're using DirectX 8, you can safely exclude the ppEffectInstance reference−it doesn't exist in that version. If you're using DirectX 9, you can set ppEffectInstance to NULL because you don't require any effects information.

The ppMaterials pointer points to an ID3DXBuffer interface, which is merely a container for data. pNumMaterials is a pointer to a DWORD variable that will contain the number of materials in a mesh that was loaded. You'll see how to use material information in a moment.

Finishing up with D3DXLoadMeshFromX, you see the actual ID3DXMesh object pointer−ppMesh. This is the interface you supply to contain your newly loaded mesh data. And there you have it! Now put all of this stuff together into a working example of loading a mesh.

Load a mesh, again called test.x, using write−only memory. After you've instanced the mesh object pointer, you need to instance an ID3DXBuffer object to contain material data and a DWORD variable to contain the number of materials.

ID3DXBuffer *pMaterials = NULL;
DWORD NumMaterials;

From here, call D3DXLoadMeshFromX.

// pDevice = pointer to a valid IDirect3DDevice9 object
D3DXLoadMeshFromX("test.x", D3DXMESH_WRITEONLY, pDevice, NULL, &pMaterials, NULL, &NumMaterials, &Mesh);

Great! If everything went as expected, D3DXLoadMeshFromX will return a success code, and your mesh will have been loaded in the ID3DXMesh interface Mesh! Of course, every single mesh contained in the .X file was crunched into a single mesh object, so how about those times when you want access to each separately−defined mesh in the file?

This is where the D3DXLoadMeshFromXof file comes in. You use the D3DXLoadMeshFromXof function in conjunction with your .X parser to load mesh data from an enumerated Mesh object. Just take a look at the D3DXLoadMeshFromXof function prototype to see what this entails.

Loads a mesh from an ID3DXFileData object.

HRESULT D3DXLoadMeshFromXof(
  LPD3DXFILEDATA pxofMesh,
  DWORD Options,
  LPDIRECT3DDEVICE9 pDevice,
  LPD3DXBUFFER * ppAdjacency,
  LPD3DXBUFFER * ppMaterials,
  LPD3DXBUFFER * ppEffectInstances,
  DWORD * pNumMaterials,
  LPD3DXMESH * ppMesh
);

Parameters

pxofMesh

[in] Pointer to an ID3DXFileData interface, representing the file data object to load.

Options

[out] Combination of one or more flags from the D3DXMESH enumeration, specifying creation options for the mesh.

pDevice

[in] Pointer to an IDirect3DDevice9 interface, the device object associated with the mesh.

ppAdjacency

[out] Pointer to a buffer that contains adjacency data. The adjacency data contains an array of three DWORDs per face that specify the three neighbors for each face in the mesh. For more information about accessing the buffer, see ID3DXBuffer.

ppMaterials

[in, out] Address of a pointer to an ID3DXBuffer interface. When the method returns, this parameter is filled with an array of D3DXMATERIAL structures.

ppEffectInstances

[out] Pointer to a buffer containing an array of effect instances, one per attribute group in the returned mesh. An effect instance is a particular instance of state information used to initialize an effect. See D3DXEFFECTINSTANCE. For more information about accessing the buffer, see ID3DXBuffer.

pNumMaterials

[in, out] Pointer to the number of D3DXMATERIAL structures in the ppMaterials array, when the method returns.

ppMesh

[out, retval] Address of a pointer to an ID3DXMesh interface, representing the loaded mesh.

Return Values

If the function succeeds, the return value is D3D_OK. If the function fails, the return value can be one of the following: D3DERR_INVALIDCALL.

Remarks

For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the D3DMATERIAL9 structure.

The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of "Texture0" with an annotation called "Name." This will contain the string file name for the texture.

Now wait a sec! D3DXLoadMeshFromXof looks almost exactly like D3DXLoadMeshFromX! The only difference is the first parameter; instead of a pointer to an .X file name to load, D3DXLoadMeshFromXof has a pointer to an ID3DXFileData object. By providing the pointer to a currently enumerated ID3DXFileData object, D3DX will take over and load all of the appropriate mesh data for you! And
since every other parameter is the same as in D3DXLoadMeshFromX, you'll have no trouble using D3DXLoadMeshFromXof in your .X parser class!

Regardless of which function you use to load the mesh data (D3DXLoadMeshFromX or D3DXLoadMeshFromXof), all you have left to do is process the material information once a mesh has been loaded into an ID3DXMesh object.

To process the material information, you need to retrieve a pointer to the material's ID3DXBuffer's data buffer (used in the call to D3DXLoadMeshFromX or D3DXLoadMeshFromXof) and cast it to a D3DXMATERIAL type. From there, iterate all materials, using the number of materials set in NumMaterials as your index. Then you need to instance an array of D3DMATERIAL9 structures and IDirect3DTexture9 interfaces to contain the mesh's material data. Use the following code to process the material information:

// Objects to hold material and texture data
D3DMATERIAL9 *Materials = NULL;
IDirect3DTexture9 *Textures = NULL;

// Get a pointer to the material data
D3DXMATERIAL *pMat;
pMat = (D3DXMATERIAL*)pMaterials−>GetBufferPointer();

// Allocate material storage space
if(NumMaterials) 
{
	Materials = new D3DMATERIAL9[NumMaterials];
	Textures = new IDirect3DTexture9*[NumMaterials];

	// Iterate through all loaded materials
	for(DWORD i=0;i<NumMaterials;i++) 
	{
		// Copy over the material information
		Materials[i] = pMat[i].MatD3D;
		// Copy diffuse color over to ambient color
		Materials[i].Ambient = Materials[i].Diffuse;
		// Load a texture if one is specified
		Textures[i] = NULL;

		if(pMat[i].pTextureFilename) 
			D3DXCreateTextureFromFile(pDevice, pMat[i].pTextureFilename, &Textures[i]);	
	}
} 
else 
{
	// Allocate a default material if none were loaded
	Materials = new D3DMATERIAL9[1];
	Textures = new IDirect3DTexture9*[1];

	// Set a default white material and no texture
	Textures[0] = NULL;
	ZeroMemory(&Materials[0], sizeof(D3DMATERIAL9));

	Materials[0].Diffuse.r = Materials[0].Ambient.r = 1.0f;
	Materials[0].Diffuse.g = Materials[0].Ambient.g = 1.0f;
	Materials[0].Diffuse.b = Materials[0].Ambient.b = 1.0f;
	Materials[0].Diffuse.a = Materials[0].Ambient.a = 1.0f;
}

// Free material data buffer
pMaterials−>Release();

You can see in the preceding code that I added a case to check whether no materials were loaded, in which case you need to create a default material to use. Once those materials are loaded, you're ready to begin using the mesh interface to render.