PhysXViewer 1.0

(Notice: Since the PhysXViewer is a DirectX 9.0 sample application it requires the DirectX 9.0 October 2006 release to be installed to build.)

The PhysXViewer is used to create tetrahedral meshes suitable for simulation with the soft body API in the 2.7 PhysX SDK. Future versions will handle rag doll models and be used to demonstrate rendering options for cloth, fluids, and rigid bodies. It is provided as a larger source code sample to assist and demonstrate how to integrate soft body into a game engine.

The PhysXViewer supports the following import and export formats:

Wavefront OBJ and TET files
EZ-Mesh
NxuStream

Wavefront OBJ and TET files: The Wavefront OBJ file format is the simplest possible graphics file format to transfer raw geometry data. This graphics format is supported by virtually all 3D authoring packages. While the graphics content is represented in the OBJ file the tetrahedral representation is described in a corresponding .TET file.

The provided SoftBody samples both use the combined OBJ and TET files to demonstrate how to load, simulate, and graphically render a SoftBody mesh.

EZ-Mesh: The EZ-mesh file format is similar to Wavefront OBJ in terms of simplicity but has been expanded to support skeletal deformed meshes. No exporter is currently available for this file format but it is sometimes convenient to use this representation. EZ-mesh also supports embedded tetrahedral geometry.

NxuStream: This is the standard serialization library for the PhysX SDK. NxuStream not only supports the complete SoftBody specification but will also annotate the tetrahedral mesh via the user properties field to indicate the source graphics mesh to bind with.

How to create a valid tetrahedral mesh using PhysXViewer:

First export your geometry as a Wavefront OBJ file.
Launch the PhysXViewer application.
Under the ‘file’ menu select ‘Import Graphics Wavefront OBJ’
Browse for your exported OBJ file and select it.
Your Wavefront OBJ file should now be visible within the graphics display.
The next step is to generate a triangle mesh from which to extract the tetrahedral geometry.

Copy Surface: Copies the original graphics mesh and optimizes it using quadratic optimization based on the value of the ‘Mesh Detail’ slider.
Iso Surface: Generates a perfect isometric surface mesh based on the subdivision detail and mesh detail sliders. An isometric surface is an evenly distributed mesh over the skin of the original object and usually provides the best results for simulation. The combination of the ‘mesh detail’ slider (which performs a quadratic approximation of the triangulated mesh) and the ‘subdivision slider’ (which controls the detail level of the isometric surface) will affect the overall detail and simulation complexity of the resulting tetrahedral mesh. By default the isometric surface will contain both an interior and exterior copy of the approximated surface. This generally produces a more robust simulation result. To eliminate the interior mesh component simply select the checkbox labeled ‘IsoSingle’

Once you have generated a source mesh with the level of detail you feel is adequate the next step is to convert it into a tetrahedral volumetric mesh. Simply click the button labeled ‘Generate Volume’ to produce the result.
Now that you have a valid tetrahedral mesh simply click on the button marked ‘Simulate SoftBody’ to see the results. Using the right mouse you should be able to select and drag the simulated soft body. To visualize the original graphics mesh using free-form deformation simply turn off the checkbox marked ‘SHOW_TETRAHEDRA’.
You may now export the results as either a Wavefront OBJ with corresponding TET file, an EZ-mesh file, or as an NxuStream data asset using the file menu.

Editing a Tetrahedral Mesh:

While viewing a tetrahedral mesh hold down the left or right shift key. Individual tetrahedron will be highlighted in yellow.
To delete a single tetrahedron hit the left mouse button while holding the shift key.
To undelete a single tetrahedron hit the right mouse button while holding the shift key.
To simulate the edited mesh click the ‘Simulate SoftBody’ button.
To go back to editing click the button ‘Stop Simulation’

Building the source code to PhysXViewer:

Go to the directory “.\Samples\PhysXViewer\compiler\vc71win32” for Visual Studio 2003 or “.\Samples\PhysXViewer\compiler\vc8win32” for Visual Studio 2005.
The PhysXViewer uses the DirectX 9.0 SDK October 2006 release. You must have this installed on your machine and the include and library paths set to build the source code.
With the PhysX SDK and the DirectX 9.0 SDK installed you should be able to build and run the PhysXViewer in both debug and release builds. The output executable is located in ‘.\bin\win32\PhysXViewer.exe’
Source to the application is located in “.\Samples\PhysXViewer\src”
The directory “.\Samples\PhysXViewer\src\common” contains general utility source code for all DirectX 9.0 sample applications.
The directory “.\Samples\PhysXViewer\src\tui” contains source code to manage the graphics user interface for the application.
The directory “.\tools\softbody” contains source code to the soft body library. This code is provided as ‘engine ready’ sample code that a developer can leverage against to quickly integrate the run-time and editing functionality into their own game engine.
The directory “.\tools\NxuStream’ contains the source code to the PhysX SDK serialization library.

User Interface:

Press F1 to toggle the user interface elements on and off.
Press ESC to exit the application.
Press TAB to toggle the console view on off.
Press HOME to return the camera to the default position.
Press SPACE to shoot a sphere into the scene
Press B to toggle between a physics visualization or a graphics visualization of the simulation.
Left mouse moves the camera view around.
WASD and the left mouse button to fly the camera around.
0-9 controls the speed at which the camera moves.
R – Resets the scene.
P – Pauses or un-pauses the simulation.
Right Mouse : Selects and drags a soft body that is being simulated.
Shift+Left Mouse: Deletes a tetrahedron
Shift + Right Mouse: Undeletes a tetrahedron.
Right Mouse + drag: Rotates a non-simulated graphics object in the view.

The PhysXViewer is a DirectX 9.0 compatible sample application. To build the source code you will need to have the Microsoft DirectX 9.0 October 2006 SDK release.

Overview

The soft body feature in the 2.7 PhysX SDK requires a new data format to be authored. The PhysXViewer allows the developer to produce this content directly from raw graphics data. The source code has been architected in such a way that it could easily be integrated into other authoring tools.

The PhysXViewer converts graphics data into a tetrahedral mesh, and then exports that data in a number of forms suitable for integration into a game engine.

Walk-Thru

To convert a raw graphics mesh into a tetrahedral mesh suitable for real-time simulation you would follow these steps.

Find a suitable graphics mesh and export it as a Wavefront OBJ file.
Launch the PhysXViewer application.
Under the ‘File’ menu select ‘Import Wavefront OBJ’
Use the file browser to select your graphics mesh.
The graphics mesh should show up in the view window and the view should automatically be adjusted relative to the size of the object.
The next step is to create a mesh, from which, the tetrahedral geometry will be extracted.

Copy Surface : This copies the original graphics mesh directly and will apply a quadratic mesh optimizer based on the results of the slider labeled ‘Mesh Detail’. The copied surface mesh will show up as a wireframe overlay. If you only want to see that outline you can select the checkbox ‘Show Graphics Mesh’ to be off. Remember to put it back on again later otherwise you will be confused with the graphics stop displaying.
Iso Surface: This is by far the preferred method of generating a mesh for tetrahedral. This runs an algorithm that ultimately produces a perfectly evenly distributed surface mesh. The detail level of this surface mesh is controlled by the slider ‘Subdivision Level’. The higher the number the more finely tessellated the mesh will be. The goal should be, however, to produce as few triangles as possible to achieve the level of simulation detail you desire. The ‘Mesh Detail’ slider affects the isosurface as well which can smooth out excessively detailed triangles on surfaces with a low degree of complexity. By default the isosurface will have both an interior and exterior shell which has been shown to produce the best quality tetrahedral meshes. You can, however, experiment with only a single isosurface by turning the checkbox labeled ‘IsoSingle’ on.

Once you have a surface mesh that you think will make a good candidate next click on the button marked ‘Generate Volume’. This will convert the triangles from the original surface into a volumetric tetrahedral mesh. The console will display new number of tetrahedral produced. Obviously the more tetrahedrons there are the more simulation time the object will require.
You can edit the tetrahedral mesh by using the left or right mouse button while holding the shift key. The left mouse will delete tetrahedrons while the right mouse button will undelete. You must click each time to affect this change. Using the right mouse button without the shift key will let you rotate the model in the view port.
To simulate the soft body using the SDK simply click on the button ‘Simulate Soft Body’
Use the right mouse button to drag the tetrahedral mesh around the scene.
Click on the checkbox labeled ‘Show Tetrahedra’ so that it is off. This will show your original graphics mesh being deformed relative to the simulated soft body.
You can tweak various soft body simulation settings such as ‘volume’, ‘stretching’, and ‘damping’ in real time by modifying the sliders.
You can toggle and tweak soft body flags by using the ‘SoftBody Flags’ menu on the main menu bar.
You can toggle various forms of debug visualization by using the ‘Debug Visualization’ menu on the main menu bar. It is important to be aware that enabling debug visualization disables asynchronous behavior.
You can toggle asynchronous behavior on and off by selecting the checkbox labeled ‘Asynchronous’. When running asynchronously the entire simulation of the soft body physics is run completely in parallel to the graphics rendering which includes the real-time deformation which is a client side graphics operation. With asynchronous mode disabled there is no parallelism and this can greatly impact the overall performance of the system.
To return to editing mode simply select ‘Stop Simulation’
At any time you can export your results in one of three file formats by using the main file menu.

Wavefront OBJ + TET : This will save out the results as a graphics file and a separate tetrahedron file. This is compatible with the SDK sample ‘SampleSoftBody’. None of the physical settings such as ‘damping’ or the soft body flags will be saved. The .TET file lists all of the tetrahedrons as well as a list of links with barycentric coordinates to the source graphics. However, we strongly recommend you do not try to use this and, instead, compute the barycentric coordinates on the fly in your own graphics engine; either at load time or embedded into your internal graphics mesh format.
EZ-Mesh: EZ-Mesh is a very simplistic graphics file format in XML. It was designed to emulate the simplicity of a Wavefront OBJ file but with additional support for hierarchal skeletons, per vertex bone weightings, and animation data. Currently no exporter exists for this format but just as it is extremely simple to export Wavefront OBJ by using a series of ‘fprintf’ statements, the same can be done for EZ-mesh. The EZ-Mesh contains both the graphics data as well as the tetrahedral data in a single file. The file can be loaded and processed using the NxuStream library.
NxuStream: This is the recommended format for anyone willing to adopt the NxuStream serialization library. This file contains the tetrahedral data as well as all of the physical parameters for the soft body. The soft body mesh contains a semantic binding to the original graphics mesh by taking advantage of the ‘userProperties’ field.

The Media Files

Located in the folder “.\Samples\PhysXViewer\media” you will find a number of pieces of sample data that you can experiment with. Many of the sample graphics files have been provided courtesy of Simutronics Corporation and are not for redistribution. They may only be used as test data.

Wavefront OBJ Files:

beshon.obj : A sample graphic of a small creature.

deer_bound.obj : A sample graphic of a deer, sample art courtesy of Simutronics Corporation

frogNormalized.obj : A sample graphics file of a frog, used by other demo scripts.

hornbug.obj : A sample graphic image of a large bug

ob_chair_gothic.obj : A sample graphic of a gothic style chair.

ob_char_wood.obj : A sample graphic of a simple wooden chair.

palmNormalized.obj : A graphic of a palm tree

wheelNormalized.obj : A graphic of a wheel used by the car demo script.

EZ-Mesh graphics files:

beshon.ezm : An EZ-mesh graphics file that graphics data with embedded tetrahedral data.

character.ezm : An EZ-mesh graphics file for a Vietnam era solider that contains per vertex bone weightings and skeletal data.

Tetrahedral files (.TET)

beshon.tet : A tetrahedron file that maps to the beshon.obj graphics file.

deer_bound.tet : A tetrahedron file that maps to the deer_bound.obj graphics file.

NxuStream files (.XML)

beshon.xml : An NxuStream file that specifies the tetrahedral geometry relative to the ‘beshon.ezm’ graphics file.

character.xml : A skinned mesh model based on the skeletal deformed mesh ‘character.ezm’. (A rag doll)

frogs.xml : A core dump file from SampleSoftBody and demonstrated with the demo script ‘frogs.psc’

frogs_hw.xml : A core dump file from SampleSoftBody and demonstrated with the demo script ‘frogs_hw.psc’ using HARDWARE

hornbug.xml : A skinned mesh (rag doll) based on the graphics mesh ‘hornbug.obj’. The skinned mesh and skeleton were completely auto-generated.

ob_chair_gothic.xml : A skinned mesh based on the graphics mesh ‘ob_chair_gothic.obj’. The skinned mesh and skeleton were completely auto-generated.

ob_chair_wood.xml : A skinned mesh based on the graphics mesh ‘ob_chair_wood.obj’. The skinned mesh and skeleton were completely auto-generated

ob_chess_table.xml : A skinned mesh based on the graphics mesh ‘ob_chess_table.obj’. The skinned mesh and skeleton were completely auto-generated

palm_tree.xml : A core dump file from SampleSoftBody and demonstrated with the demo script ‘palm_tree.psc’

soft_box_sphere.xml : A core dump file from SampleSoftBody

softcar.xml : A core dump file from SampleSoftBody and demonstrated with the demo script ‘softcar.psc’

Demo Scripts (.PSC)

frogs.psc : Demonstrates the frog falling demo running in software.

frogs_hw.psc : Demonstrates the frog falling demo running in hardware

palmtree.psc : Demonstrates the palm tree demo.

PhysXViewer.psc : Not a demo script, this file saves the current user interface settings of PhysXViewer between sessions.

softcar.psc : Demonstrates the car with soft wheels demo.

The SoftBody source code library.

Located in the ‘tools’ folder of the PhysX SDK is a source code library called ‘SoftBody’. The goal of this effort was to provide sufficient source code to demonstrate how the soft body feature, including all editing functions, into a game engine. This library is written in such a way that it could, theoretically, be dropped directly into an existing game engine and, after implementing a handful of pure virtual interfaces, would provide all of the functionality demonstrated in the PhysXViewer application.

The source code is meant primarily to act as sample code as a learning tool. It is doubtful that it would ultimately be used in a final production implementation. That said, it is quite likely that substantial portions of this code could, and should, be used directly or with slight modifications.

This code is dependent upon the PhysX SDK and the NxuStream serialization library to build. One single piece of source code has a dependency on the DirectX SDK, but it is implemented through a virtual interface such that it could easily be bound to other graphics engines. There is a small amount of STL usage in the code. It has only been compiled and tested against the Windows platform. All of the source code is encapsulated in the namespace ‘SOFTBODY’ to prevent clashing with any other source in your application.

Virtual Interfaces : TetraGraphics.h

The file ‘TetraGraphics.h’ in the SoftBody source library defines the various interfaces between the library and your application.

The ‘SoftFileInterface’ provides utility services such as mapping a file name to an absolute path or reporting error messages. It also assumes that the application owns and controls the PhysX simulations so it requests reset events and fetch results blocking calls through this interface.

TetraGraphicsVertex : Defines a general renderable graphics vertex.

TetraDeformVertex : Defines a generic graphics vertex with four bone weightings.

TetraMaterial : Defines a generic concept of a ‘material’ with a texture name and lighting information.

SoftMeshInterface : Defines a generic interface to receive materials, triangles, and tetrahedron via the sample file loading code.

TetraGraphicsInterface : Defines a simple abstract interface for 3d graphics rendering. One implementation is provided for DirectX, however, it could easily be remapped to other graphics APIs.

Integration Notes for Game Developers

Loading Wavefront OBJ files and TET files.

Wavefront OBJ files and their associated tetrahedral files can be loaded using ‘SoftMeshObj.h’ and ‘SoftMeshObj.cpp’. The only dependency is on the SoftMeshInterface to receive the results.

Loading EZ-Mesh files with embedded tetrahedral data.

EZ-Mesh files with embedded tetrahedral data can be loaded using ‘SoftMeshEZM.h’ and ‘SoftMeshEZM.cpp’. The dependencies are ‘SoftMeshInterface’ and the NxuStream library. Recently NxuStream was revised to provide support for the EZ-mesh graphics file format. While, currently, there are no exporters for this file format it is simple enough that any game developer should be able to export their skeletal deformed mesh content with just a series of ‘fprintf’ statements. A 3DS Max exporter based on the IGameExporter might be provided at some point in the future.

Rendering Graphics meshes based on a soft body simulation.

The SDK simulates soft bodies as tetrahedral meshes. However, this is rarely what you want to show up on the graphics screen. Instead you want to map the tetrahedral simulation to your graphics mesh to create a convincing visual effect.

The technique required to do this is called ‘free-form deformation’. It is a form of ‘skinning’ where each vertex, instead of being assigned to a particular bone in a rigid body simulation, is mapped to a specific tetrahedron. To perform the per-vertex deformation requires a set of barycentric co-ordinates for each vertex. In the provided sample application these barycentric co-ordinates are computed on the fly at load time and stored into each vertex. For a full game integration this data might best be precomputed and embedded into your mesh files on disk.

The code to compute the barycentric co-ordinates is dependent on ‘MeshHash.h’ and ‘MeshHash.cpp’. This utility source code places the bounding box of each tetrahedron into a hash table to speed up the building phase. To compute the barycentric co-ordinates the closest tetrahedron must be found for each vertex. The code that performs this action is located in ‘TetraMesh.cpp’ in the method ‘TetraMesh::buildLinks’ (around line number 830).

This implementation is a little bit more complicated than what you might use in your own engine since it works in concert with the tetrahedral editor and masks out tetrahedra that have been marked for deletion.

The same basic code can also be found in the SampleSoftBody demo. This is code that a graphics programmer will have to incorporate into their own graphics engine to support the soft body visualization. Since the PhysX SDK is spending its time computing the physics solution the graphics rendering pipeline, independently, must compute the graphics solution.

The actual deformation code at run-time is extremely simple. It can be found in ‘TetraMesh::applyLinks’ at roughly line number 262. The computation to deform a single vertex is simply:

NxVec3 p = p0*b.x + p1*b.y + p2.*b.z + p3*(1.0f-b.x-b.y-b.z);

Where p0, p1, p2, and p3 represent the positions of the tetrahedron and ‘b’ represents the pre-computed barycentric co-ordinate.

Since this computation is so fast it is difficult to see how to get a performance gain by pushing it into a vertex shader, however, with DirectX 10 it is quite possible a highly efficient shader could be implemented but it is hard to see how to do this with DirectX 9 class hardware.

Integrating the entire SoftBodySytem

The source code library has a single major application interface called the ‘SoftBodySystem’. The header file is ‘SoftBodySystem.h’ and the implementation is in ‘SoftBodySystem.cpp’. This implementation contains not only the functionality to load soft body meshes, simulate, and render them, but also includes all of the editing features of PhysXViewer. Simply by hooking up the call to ‘processCommand’ a game editor could easily duplicate all of the functionality in PhysXViewer directly into their own in-house tool.

It is important to remember that this is merely ‘sample’ code. It will almost always need to be modified to meet the needs of a specific engine and for certain enhanced to meet the specific needs of your product. Feel free to peruse the code and step through it as a learning exercise. The code is not yet documented but will be improved in future releases.

The File List

Here is a list of the source files in the SoftBody library and their purpose.

MeshHash.cpp and MeshHash.h : A utility to place bounding volumes into a 3d hash table for high speed queries.

NxMouseDrag.cpp and NxMouseDrag.h : A generic utility to support mouse dragging for soft bodies, cloth, and rigid bodies. This source has no dependencies other than the SDK and can be extracted and used directly in your own PhysX applications. The only input it needs is the PhysX SDK pointer, optional scene pointer, the width of the graphics screen, the height of the graphics screen, the view and projection matrix and the delta frame time.

NxTetra.h : Defines the pure virtual interface to the tetrahedral generation tool. The source code that actually converts graphics meshes to tetrahedral geometry is not provided with this release as it is considered propriety intellectual property of Ageia. The functionality has been placed into the provided DLL ‘NxTetra.dll’ that can dynamically loaded by your application.

SkinnedMesh.cpp and SkinnedMesh.h : Handles loading an asset that is comprised of a collection of physics objects, instantiating them, and rendering them. This includes a full working example of skinned mesh rag dolls as well as source to auto-generate a skeleton and per vertex bone weightings from an arbitrary collection of rigid body actors mapped to an arbitrary graphics mesh.

SoftBody.cpp and SoftBody.h : Contains the main ‘factory’ for the soft body simulation and editor.

SoftBodyMath.cpp and SoftBodyMath.h : Provides a few generic useful math functions such as ray triangle intersection. Used for raycasting when editing the tetrahedral mesh.

SoftMesh.cpp and SoftMesh.h : A simple and generic mesh class which handles either skeletal deformed meshes or static meshes.

SoftMeshEZM.cpp and SoftMeshEZM.h : Loads a graphics mesh and tetrahedrons.

SoftMeshObj.cpp and SoftMeshObj.h : Loads Wavefront OBJ files and the corresponding .TET file with tetrahedral data.

SoftServe.cpp and SoftServe.h : Contains utility source code to export the edited soft body in the three supported file formats.

SoftSkeleton.cpp and SoftSkeleton.h : Utility code to auto-generate the graphics transforms for a skeleton mapped to a set of rigid body actors.

SoftVertex.cpp and SoftVertex.h : Utility code to build indexed triangle lists of vertices. This is the only source file to use the STL.

TetraD3D.cpp and TetraD3D.h : The DirectX implementation of the TetraGraphicsInterface. By replacing this with an implantation of your own you could, theoretically, bind this entire library directly to your own graphics engine.

TetraGraphics.cpp and TetraGraphics.h : Defines the pure virtual interfaces and graphics structures for rendering.

TetraMesh.cpp and TetraMesh.h : Handles management, editing, and rendering of tetrahedral and corresponding graphics meshes.

CreateDynamics

The last button on the PhysXViewer application in labeled ‘dynamics page’. This shows how the PhysXViewer application binds to the utility plug-in DLL called ‘CreateDynamics.dll’. This tool is designed to assist developers by automatically generating physics content directly from graphics data based on a set of sliders and checkboxes that an artist or designer can control.

This project is incomplete, undocumented, and highly experimental. The demos of the soldier character as well as the skinned mesh chairs were created with this tool. It can perform convex decomposition on a generic mesh and convert skeletal deformed meshes into approximate rag dolls.

This project was created and is maintained by John W. Ratcliff (mailto: jratcliff@infiniplex.net). John will be presenting this project formally at GDC 2007 in a 60 minute talk and intends to be able to release the full source code, with documentation as well as many improvements in algorithms and stability at that time.