Benjamin Yang · EAE 6320

Assignment 06

A human-readable mesh file format, a MeshBuilder tool, and meshes loaded from disk instead of hard-coded

⬇ Download the game (Direct3D, x64) ⬇ OpenGL build (x86) Unzip anywhere and double click MyGame.exe. ESC closes the game. Arrow keys move the colored square, hold SPACE to give it the triangle mesh, hold SHIFT to draw it white. W/A/S/D move the camera and Q/E turn it.

Screenshots

Start of the game (Direct3D, x64)
Start of the game (Direct3D, x64). Nothing in this picture is hard-coded any more: the colored square comes from square.mesh, the white spinner from triangle.mesh, and the white plane under them is a new floor.mesh (an 8 x 8 plane in the xz plane, one unit below the origin) that I added only by writing a file and listing it in AssetsToBuild.lua.
The OpenGL (x86) build at the start of the game, identical to Direct3D
The OpenGL (x86) build at the start of the game, identical to Direct3D. The same three mesh files are copied into both builds' data folders.
S held for 1
S held for 1.5 seconds: the camera backed away and the floor's edges and perspective become visible. The floor is 9 vertices and 8 triangles in floor.mesh.
SPACE held: the player object uses the triangle mesh, the same file the spinner uses (one cMesh shared by two objects, as in Assignment 05)
SPACE held: the player object uses the triangle mesh, the same file the spinner uses (one cMesh shared by two objects, as in Assignment 05).
Checklist test: the line { 0, 2, 3 } was deleted from square
Checklist test: the line { 0, 2, 3 } was deleted from square.mesh, only BuildMyGameAssets was rebuilt, and the game was run again with no code changes. The square is missing its upper-left triangle; the triangle count came from the file.
Checklist test: vertex 2 was changed from (1, 1, 0) to (2, 1, 0) in square
Checklist test: vertex 2 was changed from (1, 1, 0) to (2, 1, 0) in square.mesh, only the assets were rebuilt, and the shape changed accordingly. The file was restored afterwards.
Debugging MeshBuilder in Visual Studio: the debugger is stopped on the first line of main() in EntryPoint
Debugging MeshBuilder in Visual Studio: the debugger is stopped on the first line of main() in EntryPoint.cpp (yellow arrow, and the call stack window shows MeshBuilder.exe!main at line 14). MeshBuilder.exe was started under the debugger with the two command arguments that AssetBuildFunctions.lua passes when it builds square.mesh: the source path in MyGame_/Content/meshes and the target path in the game's data/meshes folder.
The editor area of the same debugging session, enlarged: the yellow arrow on the opening brace of main() in EntryPoint
The editor area of the same debugging session, enlarged: the yellow arrow on the opening brace of main() in EntryPoint.cpp, the process box showing meshbuilder.exe, and the call stack entry MeshBuilder.exe!main(...) line 14.
The TA scenario: MyGame
The TA scenario: MyGame.exe started from a folder with no data/. The mesh file isn't found, cMesh::Load() fails, initialization fails, and the game shows this message and exits with code 1 instead of crashing.

Why human-readable asset files

Until this week the geometry of every mesh was a C++ array inside cMyGame.cpp. That is the worst place for content: changing one coordinate meant recompiling and relinking the game, nobody but a programmer could do it, and the data was tied to one game. Moving it into text files that the game reads at run time gives several things at once:

The price is that a Lua file is slower to load and bigger than a binary one, and the game currently links the whole Lua library just to read it. That is the right trade-off for the source format: when load time matters (a future assignment) MeshBuilder will convert these files to a binary format and the game will read that, while the human-readable file stays the thing that people edit.

A mesh file

This is MyGame_/Content/Meshes/square.mesh exactly as it is in the repository. The source files use the extension .mesh; the built files in data/Meshes/ keep the same name and extension for now, since MeshBuilder only copies them.

--[[
	A unit square with its lower-left corner at the object's origin
	(the same rectangle as Assignment 02, so that the reference image can be reproduced)

	Mesh files are Lua tables:
	* positions are in the object's local space (right-handed, +y up, +z toward the viewer)
	* each vertex is a dictionary so that more data (color, normal, texture coordinates, ...)
	  can be added to it later without touching the existing values
	* vertex indices start at 0 (the same number that the GPU uses in the index buffer)
	* each triangle lists its three vertices counter-clockwise when looking at its front side
	* the "-- n:" comments on the vertices are only there to help a human count;
	  nothing reads them, so adding or removing vertices never requires renumbering anything
]]

return
{
	vertices =
	{
		{ position = { x = 0.0, y = 0.0, z = 0.0 } },	-- 0: lower left
		{ position = { x = 1.0, y = 0.0, z = 0.0 } },	-- 1: lower right
		{ position = { x = 1.0, y = 1.0, z = 0.0 } },	-- 2: upper right
		{ position = { x = 0.0, y = 1.0, z = 0.0 } },	-- 3: upper left
	},

	triangles =
	{
		{ 0, 1, 2 },	-- lower-right half
		{ 0, 2, 3 },	-- upper-left half
	},
}

triangle.mesh has three vertices and one triangle, and floor.mesh has nine vertices in three rows and eight triangles grouped by square, with a comment above each group.

Design choices

The guiding question for every piece of data was the one from class: would it be OK to change the order of this data? If yes it should be a dictionary with named keys, if no it must be an array. The resulting choices, including the ones I went back and forth on:

MeshBuilder

MeshBuilder is a new console project in Tools/ (on disk and in Solution Explorer) with the same property sheets as ShaderBuilder and references to AssetBuildLibrary, Platform, Windows and Asserts. EntryPoint.cpp is ShaderBuilder's with "Shader" replaced by "Mesh", and cMeshBuilder only overrides iBuilder::Build():

eae6320::cResult eae6320::Assets::cMeshBuilder::Build( const std::vector<std::string>& i_arguments )
{
	std::string errorMessage;
	constexpr bool shouldFunctionFailIfTargetAlreadyExists = false;
	constexpr bool shouldTargetFileTimeBeModified = true;
	const auto result = Platform::CopyFile( m_path_source, m_path_target,
		shouldFunctionFailIfTargetAlreadyExists, shouldTargetFileTimeBeModified, &errorMessage );
	if ( !result )
	{
		OutputErrorMessageWithFileInfo( m_path_source, "Failed to copy the mesh to \"%s\": %s", m_path_target, errorMessage.c_str() );
	}
	return result;
}

Platform::CopyFile() from the Platform project does the platform-independent copy; the two flags make it overwrite an existing built file and update the target's time stamp so the asset build system sees that the built file is newer than its source. On failure the error goes through OutputErrorMessageWithFileInfo() so that it appears in Visual Studio's Error List with the mesh path (double clicking it opens the file), and the failure result makes AssetBuildExe stop the build.

Two Lua files tell the build system about meshes. AssetBuildFunctions.lua registers the asset type; it only needs the builder's name, the default built path (same name and extension) and the default dependency check are fine for meshes:

NewAssetTypeInfo( "meshes",
	{
		GetBuilderRelativePath = function()
			return "MeshBuilder.exe"
		end,
	}
)

AssetsToBuild.lua lists the three files. A mesh needs no arguments, so each entry is just the path string:

	meshes =
	{
		"Meshes/square.mesh",
		"Meshes/triangle.mesh",
		"Meshes/floor.mesh",
	},

The project that needs MeshBuilder to be built before it can build is BuildMyGameAssets, because its custom build step runs AssetBuildExe, which runs MeshBuilder.exe; so BuildMyGameAssets got a project dependency (not a reference) on MeshBuilder in the solution, next to its existing ones on ShaderBuilder and AssetBuildExe. Building the solution from an empty temp/ folder now prints "Built ...meshes/square.mesh" and so on, and the data/meshes/ folder appears in the install directory.

Loading a mesh

The factory function changed from taking arrays to taking a path:

// before (Assignment 05)
static cResult Load( const VertexFormats::sVertex_mesh* const i_vertexData, const uint16_t i_vertexCount,
	const uint16_t* const i_indexData_counterClockwise, const unsigned int i_indexCount, cMesh*& o_mesh );
// now
static cResult Load( const char* const i_path, cMesh*& o_mesh );

The game calls Graphics::cMesh::Load( "data/Meshes/square.mesh", m_mesh_rectangle ). Load() reads the file into two std::vectors, allocates the mesh, and passes vertices.data(), vertices.size(), indices.data() and indices.size() to the unchanged platform-specific Initialize(), so cMesh.d3d.cpp and cMesh.gl.cpp did not change at all. The vectors are freed when Load() returns; the GPU buffers are the only copy that survives. The Graphics project now references LuaLib.

The Lua part follows the ReadNestedTableValues example: one function per nesting level, each one finding the table it needs at the top of the stack and popping everything it pushed before returning, using a cScopeGuard so that early returns on errors still leave the stack balanced (the closing scope guard asserts that the stack is empty before lua_close()). The structure mirrors the file:

LoadMeshFile( path, vertices, indices )          // luaL_newstate, luaL_loadfile, lua_pcall, check that one table came back
  LoadTableValues( ... )
    LoadTableValues_vertices( ... )               // get "vertices", luaL_len, loop lua_rawgeti( -1, i )
      LoadTableValues_vertex( ..., vertexNumber )  // get "position", then "x", "y", "z" as numbers
    LoadTableValues_triangles( ... )              // get "triangles", luaL_len, resize indices to 3 * count
      LoadTableValues_triangle( ..., n )           // rawgeti 1..3, lua_isinteger, range check, store as uint16_t

Only the two outer arrays are iterated, because their length is unknown; everything else is looked up by key or by a fixed index (a position always has x, y, z and a triangle always has three entries), so the non-deterministic order of dictionary keys never matters. Every check produces a specific error through Logging::OutputError() (and an assert in debug builds): a missing table, a non-number coordinate, a triangle with the wrong number of entries, a vertex number out of range, more than 65536 vertices. Those messages are what make a content problem distinguishable from a code problem.

Debugging MeshBuilder

MeshBuilder is run by the asset build system, not by hand, so to debug it Visual Studio has to be given the same command line. The arguments can be seen by uncommenting print( commandLine ) in BuildAsset() in AssetBuildFunctions.lua and rebuilding BuildMyGameAssets after deleting temp/: every ShaderBuilder.exe and MeshBuilder.exe command is then printed in the Output window. Everything after the exe path (the quoted source path and the quoted target path) goes into the MeshBuilder project's Debugging > Command Arguments; with MeshBuilder set as the startup project, F11 stops on the first line of main() in EntryPoint.cpp, which is the screenshot above. Stepping into Build<cMeshBuilder>() leads through ParseCommandArgumentsAndBuild(), which splits the arguments into m_path_source and m_path_target, to cMeshBuilder::Build(), where the two paths can be inspected before the copy happens. (Starting the exe with devenv /DebugExe and the same two arguments gives the same session.)

Notes