(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
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
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
NxuStream: This is the standard serialization library
for the PhysX SDK.
NxuStream not only
How to create a valid
tetrahedral mesh using PhysXViewer:
Editing a Tetrahedral
Mesh:
Building the source code to PhysXViewer:
User Interface:
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.
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
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
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
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
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
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.