Benjamin Yang · EAE 6320

Assignment 07

A Maya plug-in that exports meshes in my human-readable format, three meshes made in Maya, depth buffering, and vertex colors

⬇ Download the game (Direct3D, x64) ⬇ OpenGL build (x86) Unzip anywhere and double click MyGame.exe. ESC closes the game. Arrow keys move the sphere, hold SPACE to give it the triangle mesh, hold SHIFT to draw it with the plain vertex-color effect. 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). All three meshes come from Maya: the 8 x 8 floor plane with a different vertex color in each corner, the sphere (the movable object, drawn with the animated color effect multiplied by its vertex colors), and the coil on the left (the spinner, white effect, so it shows its vertex colors as they are). Nearer surfaces hide farther ones because depth testing and depth writing are on.
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.
SHIFT held: the sphere is drawn with the plain effect, which shows the vertex colors I painted in Maya (orange at the bottom to yellow at the top)
SHIFT held: the sphere is drawn with the plain effect, which shows the vertex colors I painted in Maya (orange at the bottom to yellow at the top). The coil has magenta, cyan and yellow bands.

The meshes from Maya

All three meshes are Maya polygon primitives with vertex colors, exported with my plug-in into MyGame_/Content/Meshes/ and listed in AssetsToBuild.lua next to the hand-written ones from Assignment 06. The Maya scenes are saved in MyGame_/Maya/ (floor.ma, sphere.ma, coil.ma) so they can be changed and re-exported later.

MeshMayaExported
floor.mesh (floor, white effect)Plane 8 x 8, 1 x 1 subdivisions4 vertices, 2 triangles
sphere.mesh (movable object)Sphere radius 0.5, 24 x 161488 vertices, 720 triangles
coil.mesh (spinner)Helix, 3 coils, height 1.58664 vertices, 4340 triangles

The exported vertex counts are higher than Maya's because the exporter makes one engine vertex for every distinct combination of position, normal, tangent, texture coordinate and color. Where a UV seam or a hard edge meets a position, Maya stores one point but the GPU needs two vertices.

Instead of clicking through the menus three times I wrote the steps down as a script, MyGame_/Maya/create_and_export_meshes.py. It runs in Maya's Python (mayapy), creates each primitive, paints its vertex colors, saves the .ma file and exports it with cmds.file( ..., type="Benjamin Yang's EAE6320 Mesh Format", exportSelected=True ). That is exactly what File > Export Selection does in the Maya window, so the meshes can also be made by hand.

Depth buffering

The effects already took render state bits when they were created, so turning depth buffering on was two lines in the render state that both of the game's effects share:

uint8_t renderStateBits = 0;
Graphics::RenderStates::DisableAlphaTransparency( renderStateBits );
// Objects now live in a 3D world, so nearer ones should hide farther ones
Graphics::RenderStates::EnableDepthTesting( renderStateBits );
Graphics::RenderStates::EnableDepthWriting( renderStateBits );
// The spinner turns its back to the camera half of the time and should still be visible
Graphics::RenderStates::EnableDrawingBothTriangleSides( renderStateBits );

The MayaMeshExporter project

The provided project is in Tools/MayaMeshExporter/ on disk and in the Tools folder in Solution Explorer, next to MeshBuilder and ShaderBuilder. It got a new project GUID, the v143 toolset, and my own target names, eae6320_OWNBY_YangBenjamin_mesh and eae6320_OWNBY_YangBenjamin_mesh_DEBUG. The paths come only from environment variables: the Maya headers and libraries from $(DEVKIT_LOCATION)\include\ and $(DEVKIT_LOCATION)\lib\, and a custom build step copies the .mll to $(MAYA_PLUG_IN_PATH), where Maya's Plug-in Manager finds both builds.

The plug-in only has an x64 platform. In the Configuration Manager every solution platform (x64 and x86) builds its x64 configuration. A plug-in is a DLL that Maya loads into its own process, and Maya is 64-bit only, so a 32-bit plug-in could never be loaded. Maya's libraries are also 64-bit only, so it could not even be linked. Building it while building the 32-bit OpenGL game is fine, because the plug-in has nothing to do with the game's platform.

What references did I have to add to MayaMeshExporter? None. The plug-in links only Maya's libraries (Foundation.lib and OpenMaya.lib, through #pragma comment in Windows/ExternalLibraries.win.h, found in $(DEVKIT_LOCATION)\lib\). The only engine file it uses is Engine/Windows/Includes.h, so that windows.h is included the same way as everywhere else. That file is header-only and the include path comes from the EngineDefaults property sheet, so no engine library has to be linked. The plug-in runs inside Maya, not inside the game, so it shouldn't link engine code it doesn't need.

What other projects depend on MayaMeshExporter? None. Neither the game nor BuildMyGameAssets needs it. The exporter is run by a person in Maya, and its output (the .mesh files) is committed under MyGame_/Content/Meshes/. From there the normal asset build copies those files with MeshBuilder, the same way it handles the hand-written meshes. If BuildMyGameAssets depended on the exporter, building the game would need the Maya devkit and the environment variables. To check this, I cloned the tag into an empty folder, unset the three Maya variables, and built only MyGame and BuildMyGameAssets in all four configurations. They built and produced all five meshes.

What the exporter writes

The plug-in writes the same Lua format that I designed by hand in Assignment 06 (vertices are an array of dictionaries, triangles are an array of { a, b, c } counted from 0 and listed counter-clockwise), with a few comments added. This is the start of the exported floor:

return
{
	-- Exported from Maya by Benjamin Yang's EAE6320 mesh exporter
	-- 4 vertices, 2 triangles

	vertices =
	{
		{	-- 0
			position = { x = -4, y = 0, z = 4 },
			color = { r = 0.1, g = 0.3, b = 0.9, a = 1 },
			normal = { x = 0, y = 1, z = 0 },
			tangent = { x = 1, y = 0, z = 0 },
			bitangent = { x = 0, y = 0, z = -1 },
			texcoord = { u = 0, v = 0 },
		},
		-- ... vertices 1 to 3 look the same ...
	},

	triangles =
	{
		{ 0, 1, 2 },	-- 0
		{ 2, 1, 3 },	-- 1
	},
}

Maya is right-handed with +y up, winds triangles counter-clockwise and puts the UV origin at the lower left. Those are the conventions my format uses, so nothing is converted. The Direct3D-specific index swap still happens only in cMesh.d3d.cpp.

Did I export the unused data? Yes. Every vertex also has its normal, tangent, bitangent and texture coordinate, even though the engine reads only position and color for now. I chose this because re-exporting is the expensive step: it means opening every Maya file and exporting every mesh again by hand. Lighting and texturing are on the way, and when they arrive the data will already be in the files. Only the loader has to change. The format makes this free to ignore: the loader looks values up by name, so it never sees the keys it doesn't ask for, and the Assignment 06 meshes without these keys still load. The cost is size (coil.mesh is 3.2 MB of text) and parse time. That's acceptable for the human-readable source format, and a binary built format can drop whatever the game doesn't use.

Debugging the plug-in

Visual Studio attached (native code) to Maya, stopped in initializePlugin() in EntryPoint
Visual Studio attached (native code) to Maya, stopped in initializePlugin() in EntryPoint.cpp as Maya loads the DEBUG build of the plug-in. The process box shows the Maya process, and the call stack shows eae6320_OWNBY_YangBenjamin_mesh_DEBUG.mll!initializePlugin(...) line 35, so the plug-in and its symbols are loaded.
The same moment, enlarged: the yellow arrow on the first line of initializePlugin()
The same moment, enlarged: the yellow arrow on the first line of initializePlugin().
After continuing, Maya exports a cube with
After continuing, Maya exports a cube with "Benjamin Yang's EAE6320 Mesh Format -- DEBUG" and the debugger stops in cMayaMeshExporter::writer(), before the vertex data is gathered.

The debugger was attached to mayapy.exe, which is Maya running without its window (the same program that runs my export script). Once it was waiting, I set breakpoints in initializePlugin() and writer(), used Debug > Attach to Process with the code type set to Native, then loaded eae6320_OWNBY_YangBenjamin_mesh_DEBUG and exported a cube. One thing went wrong first: with the code type left on automatic, the breakpoints were never hit. Choosing Native code fixed it, which is what the assignment warns about.

Too many vertices

The limit is 65536 vertices per mesh, because the index buffer stores each index as a 16-bit uint16_t. A triangle can therefore only refer to vertices 0 to 65535. A larger mesh can't be drawn with 16-bit indices, and the engine is meant to keep that limit for now.

To test it I exported a sphere with 260 x 260 subdivisions (67342 Maya points, 269880 exported vertices) and copied it over sphere.mesh. Both sides handle it without crashing:

The game with a 269880-vertex sphere
The game with a 269880-vertex sphere.mesh: no crash and no garbled mesh, just this message, the reason in the log, and a clean exit.

While testing the limit I found a bug at the boundary. A mesh with exactly 65536 vertices passed the check, but Load() then passed static_cast<uint16_t>( vertices.size() ) to Initialize(), and 65536 wraps around to 0. Indices must fit in 16 bits but the count of vertices doesn't, so Initialize() now takes the vertex count as unsigned int. A 65536-vertex mesh is therefore created with all of its vertices.

Re-exporting the movable object

Checklist test: a green torus made in Maya was exported over sphere
Checklist test: a green torus made in Maya was exported over sphere.mesh, the solution was built and the game run. The movable object is now the torus, with no code change (shown with SHIFT held; OpenGL looks the same). sphere.mesh was restored afterwards.

Vertex colors (optional challenge)

Notes