History: PhysX Candy Wrapper

Source of version: 22 (current)

The [http://eyecm-physx.sourceforge.net/|PhysX Candy Wrapper for .NET] is a wrapper library for the [http://en.wikipedia.org/wiki/PhysX|PhysX] physics engine currently owned by Nvidia, although it was originally developed by Ageia. The wrapper is open source and is designed to be integrated with the math library of your choice. 

%info% For questions, bug reports, etc. use this [http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=10776|forum topic].

{maketoc}

In our case we are using the math library is built into ((MOGRE|Mogre)) due to the design of Ogre. There is a working ((MOGRE|Mogre)) binding available for download on the wrapper website. With the Mogre binding all of the wrappers methods are directly compatible with classes like ''Mogre.Vector3'', ''Mogre.Quaternion'', and so on. This approach makes things a lot easier and removes the need for yet another wrapper around ((NxOgre)) for example.

__Depency:__
You need to install the [http://www.nvidia.com/object/physx-9.10.0513-driver.html|PhysX System Software].
!PhysX SDK
It's profitable to install the PhysX SDK. This can be downloaded from the from NVidia website. The Windows version is completely free for both commercial and non-commercial use. You'll only need to pay a fee if you intend on releasing your game for the PS3, XBox or Wii. It's not open source, but it has been used in a many commercial games so it's heavily battle tested in the real world. 
http://developer.nvidia.com/object/physx_downloads.html

For some reason NVidia has stopped providing the SDK download as a direct link from the download page. You now have to sign up and go through the PhysX developer support page. My experience with this process was long, tedious and annoying. If you are in a hurry it's not hard to google a direct download link to a previous version of the SDK while your waiting for NVidia to get there act together.
http://www.softpedia.com/progDownload/NVIDIA-PhysX-SDK-Download-104786.html

!PhysX Candy Wrapper SDK
The wrapper is open source and can be downloaded from SourceForge. Although there is limited documentation, most of the code can be translated from the PhysX documentation fairly easily. There is also some bits and pieces floating around on the forums. It's my hope by making this wiki page that this situation improves. Even if the wrapper is no longer maintained, at least it's open source and can be taken over by other developers.
http://sourceforge.net/projects/eyecm-physx/files/eyecm-physx-mogre/

!Implementation
(note: the following code was taken from my current project may be missing something, if you find any errors please correct them)

The first thing you will want to do is add a reference to the PhysX candy wrapper DLL to your Mogre project. Once this is done you'll have access to the wrapped classes under the namespace Mogre.PhysX;

What I did in my game engine was create a thin physics manager class for the purpose of holding common functionality and potentially making it easier to use a different physics engine if the day comes. Firstly add this line to the top of your physics manager class.
{CODE(wrap="1", colors="c#")}
using Mogre.PhysX;
{CODE}

Next, you can add some private variables to the class that control the physics controller root and the scene (kind of like the SceneManager in Ogre).

{CODE(wrap="1", colors="c#")}        
private Physics physics;
private Scene scene;
{CODE}

Okay, that's the easy stuff out of the road. Now for the initialisation method that should be called somewhere as your game loads. I call it just after initailising Ogre.

{CODE(wrap="1", colors="c#")}
public bool Initiliase()
{            
    // create the root object
    this.physics = Physics.Create();
    this.physics.Parameters.SkinWidth = 0.0025f;

    // setup default scene params
    SceneDesc sceneDesc = new SceneDesc();
    sceneDesc.SetToDefault();
    sceneDesc.Gravity = new Vector3(0, -9.8f, 0);
    sceneDesc.UpAxis = 1; // NX_Y in c++ (I couldn't find the equivilent enum for C#)
    
    // your class should implement IUserContactReport to use this
    //sceneDesc.UserContactReport = this;

    this.scene = physics.CreateScene(sceneDesc);

    // default material
    scene.Materials[0].Restitution = 0.5f;
    scene.Materials[0].StaticFriction = 0.5f;
    scene.Materials[0].DynamicFriction = 0.5f;

    // begin simulation
    this.scene.Simulate(0);
    return true;
}
{CODE}

After that you'll want to call an Update method in your main game / rendering loop (frameStarted for example).

{CODE(wrap="1", colors="c#")}
public void Update(float deltaTime)
{
    this.scene.FlushStream();
    this.scene.FetchResults(SimulationStatuses.AllFinished, true);
    this.scene.Simulate(deltaTime);
}
{CODE}

And don't forget to be a good little programmer and clean up your resources. This should get called when your game exits. I'm not sure if it's absolutely required in managed code but it's better to be safe than sorry when we are dealing with unmanaged wrappers.

{CODE(wrap="1", colors="c#")}
public void Dispose()
{
   this.physics.Dispose();
}
{CODE}

That's about it for the basics. You're game now has a working physics engine, although, it won't do much because you haven't setup any actors or collision shapes.

!Solid things that move
To make your game more interesting, you'll want to give physical properties to the models in your game. PhysX likes to call these Actors. You set up an actor by providing it the details of it's shape, mass and if it's static or dynamic.

Strictly speaking, the physics engine knows nothing about the graphics engine in your game. You need to tell the actors from the physics engine how to move the scene nodes from the graphics engine. For this reason, you might want to create a class the ties together an actor and a scene node. When you want your physics engine to move the scene nodes around you simply call the Update method from inside your game loop.

{CODE(wrap="1", colors="c#")}
public class ActorNode
{
	private SceneNode sceneNode;
	private Actor actor;

	public ActorNode(SceneNode sceneNode, Actor actor)
	{
	    this.sceneNode = sceneNode;
	    this.actor = actor;
	}

	internal void Update(float deltaTime)
	{
	    if (!actor.IsSleeping)
	    {
		this.sceneNode.Position = actor.GlobalPosition;
		this.sceneNode.Orientation = actor.GlobalOrientationQuaternion;
	    }
	}
}
{CODE}

But before you can do anything with this class you'll need to know how to create actors. Typically speaking, you'll want to move an Entity around with an actor, although it's not required that you have an Entity attached. For example you may also want to control the camera or lights with the physics engine. To keep things simple, lets crate a sphere around the well known ogrehead.mesh.

{CODE(wrap="1", colors="c#")}
float scale = 0.1f;
int id = 0;

// graphics
Entity entity = sceneManager.CreateEntity("ogreHead" + id.ToString(), "ogrehead.mesh");
SceneNode sceneNode = sceneManager.RootSceneNode.CreateChildSceneNode();
sceneNode.AttachObject(entity);
sceneNode.Position = new Vector3(0, 10, 0);
sceneNode.Scale = Vector3.UNIT_SIZE * scale;

// physics
// attaching a body to the actor makes it dynamic, you can set things like initial velocity
BodyDesc bodyDesc = new BodyDesc();
bodyDesc.LinearVelocity = new Vector3(0, 2, 5);

// the actor properties control the mass, position and orientation
// if you leave the body set to null it will become a static actor and wont move
ActorDesc actorDesc = new ActorDesc();
actorDesc.Density = 4;
actorDesc.Body = bodyDesc;
actorDesc.GlobalPosition = sceneNode.Position;
actorDesc.GlobalOrientation = sceneNode.Orientation.ToRotationMatrix();

// a quick trick the get the size of the physics shape right is to use the bounding box of the entity
actorDesc.Shapes.Add(new SphereShapeDesc(entity.BoundingBox.HalfSize * scale, entity.BoundingBox.Center * scale));

// finally, create the actor in the physics scene
Actor actor = scene.CreateActor(actorDesc);

// create our special actor node to tie together the scene node and actor that we can update its position later
ActorNode actorNode = new ActorNode(sceneNode, actor);
actorNodeList.Add(actorNode);
{CODE}

Now all you have to do is update your actor nodes in your game loop. There are some optimisations that can be applied to this later, but lets keep it simple for now.

{CODE(wrap="1", colors="c#")}
foreach (ActorNode actorNode in actorNodeList)
	actorNode.Update(deltaTime);
{CODE}

You should be able to run your game and see the ogre head falling off the screen, of course, this isn't very useful because you don't have a floor for it to bounce off. Lets add one. Static actors like the floor or your level geometry don't need to be added to the actorNodeList because they won't move.

{CODE(wrap="1", colors="c#")}
// creating an invisible static plane is really simple
ActorDesc actorDesc = new ActorDesc(new PlaneShapeDesc());
scene.CreateActor(actorDesc);
{CODE}

Next up we'll take a look at something more difficult but very powerful.

!Dealing with Triangle Mesh shapes

One of the more difficult tasks is telling the physics engine about the triangle mesh shapes in your game world. When your taking this approach you should realise that it's not as fast as bounding things in your game world with simple shapes like spheres and boxes. However, it is very useful (and more appropriate) in some situations like the general geometry of your level or odd shapes that sphere's and boxes don't fit very well.

But before you can do this with Ogre / Mogre you'll need to extract the vertices and triangles out of your entities. Here's a class that's very useful for doing so.

{CODE(wrap="1", colors="c#")}
public class StaticMeshData
{
	private Vector3[] vertices;
	private uint[] indices;
	private MeshPtr meshPtr;
	private Vector3 scale = Vector3.UNIT_SCALE;

	public float[] Points
	{
		get
		{
			// extract the points out of the vertices
			float[] points = new float[this.Vertices.Length * 3];
			int i = 0;

			foreach (Vector3 vertex in this.Vertices)
			{
				points[i + 0] = vertex.x;
				points[i + 1] = vertex.y;
				points[i + 2] = vertex.z;
				i += 3;
			}

			return points;
		}
	}

	public Vector3[] Vertices
	{
		get
		{
			return this.vertices;
		}
	}

	public uint[] Indices
	{
		get
		{
			return this.indices;
		}
	}

	public int TriangleCount
	{
		get
		{
			return this.indices.Length / 3;
		}
	}

	public StaticMeshData(MeshPtr meshPtr)
	{
		Initiliase(meshPtr, Vector3.UNIT_SCALE);
	}

	public StaticMeshData(MeshPtr meshPtr, float unitScale)
	{
		Initiliase(meshPtr, Vector3.UNIT_SCALE * unitScale);
	}

	public StaticMeshData(MeshPtr meshPtr, Vector3 scale)
	{
		Initiliase(meshPtr, scale);
	}

	private void Initiliase(MeshPtr meshPtr, Vector3 scale)
	{
		this.scale = scale;
		this.meshPtr = meshPtr;

		PrepareBuffers();
		ReadData();
	}

	private void ReadData()
	{
		int indexOffset = 0;
		uint vertexOffset = 0;

		// read the index and vertex data from the mesh
		for(ushort i = 0; i < meshPtr.NumSubMeshes; i++)
		{
			SubMesh subMesh = meshPtr.GetSubMesh(i);

			indexOffset = ReadIndexData(indexOffset, vertexOffset, subMesh.indexData);

			if(subMesh.useSharedVertices == false)
				vertexOffset = ReadVertexData(vertexOffset, subMesh.vertexData);
		}

		// add the shared vertex data
		if(meshPtr.sharedVertexData != null)
			vertexOffset = ReadVertexData(vertexOffset, meshPtr.sharedVertexData);
	}

	private void PrepareBuffers()
	{
		uint indexCount = 0;
		uint vertexCount = 0;

		// Add any shared vertices
		if(meshPtr.sharedVertexData != null)
			vertexCount = meshPtr.sharedVertexData.vertexCount;

		// Calculate the number of vertices and indices in the sub meshes
		for (ushort i = 0; i < meshPtr.NumSubMeshes; i++)
		{
			SubMesh subMesh = meshPtr.GetSubMesh(i);

			// we have already counted the vertices that are shared
			if(subMesh.useSharedVertices == false)
				vertexCount += subMesh.vertexData.vertexCount;

			indexCount += subMesh.indexData.indexCount;
		}

		// Allocate space for the vertices and indices
		vertices = new Vector3[vertexCount];
		indices = new uint[indexCount];
	}

	private unsafe uint ReadVertexData(uint vertexOffset, VertexData vertexData)
	{
		VertexElement posElem = vertexData.vertexDeclaration.FindElementBySemantic(VertexElementSemantic.VES_POSITION);
		HardwareVertexBufferSharedPtr vertexBuffer = vertexData.vertexBufferBinding.GetBuffer(posElem.Source);
		byte* vertexMemory = (byte*)vertexBuffer.Lock(HardwareBuffer.LockOptions.HBL_READ_ONLY);
		float* pElem;

		for (uint i = 0; i < vertexData.vertexCount; i++)
		{
			posElem.BaseVertexPointerToElement(vertexMemory, &pElem);

			Vector3 point = new Vector3(pElem[0], pElem[1], pElem[2]);
			vertices[vertexOffset] = point * this.scale;
			vertexMemory += vertexBuffer.VertexSize;
			vertexOffset++;
		}

		vertexBuffer.Unlock();
		return vertexOffset;
	}
	private unsafe int ReadIndexData(int indexOffset, uint vertexOffset, IndexData indexData)
	{
		// get index data
		HardwareIndexBufferSharedPtr indexBuf = indexData.indexBuffer;
		HardwareIndexBuffer.IndexType indexType = indexBuf.Type;
		uint* pLong = (uint*)(indexBuf.Lock(HardwareBuffer.LockOptions.HBL_READ_ONLY));
		ushort* pShort = (ushort*)pLong;

		for (uint i = 0; i < indexData.indexCount; i++)
		{
			if(indexType == HardwareIndexBuffer.IndexType.IT_32BIT)
				indices[indexOffset] = pLong[i] + vertexOffset;
			else
				indices[indexOffset] = pShort[i] + vertexOffset;

			indexOffset++;
		}

		indexBuf.Unlock();
		return indexOffset;
	}
}
{CODE}

Now that you have a way of extracting the triangle mesh you can use this to cook meshes used by the physics engine. The reason you need to cook them first is because PhysX will optimise the meshes for physics calculations. This may be very different to the mesh used for graphics.

There are two types of mesh shapes in PhysX. The first is a convex hull shape. This is ideal for dynamic objects because it's a lot faster to calculate collisions with convex shapes then it is with concave ones (I won't go into the reasons right now).

{CODE(wrap="1", colors="c#")}
public ConvexShapeDesc CreateConvexHull(StaticMeshData meshData)
{
    // create descriptor for convex hull
    ConvexShapeDesc convexMeshShapeDesc = null;
    ConvexMeshDesc convexMeshDesc = new ConvexMeshDesc();
    convexMeshDesc.PinPoints<float>(meshData.Points, 0, sizeof(float) * 3);
    convexMeshDesc.PinTriangles<uint>(meshData.Indices, 0, sizeof(uint) * 3);
    convexMeshDesc.VertexCount = (uint)meshData.Vertices.Length;
    convexMeshDesc.TriangleCount = (uint)meshData.TriangleCount;
    convexMeshDesc.Flags = ConvexFlags.ComputeConvex;

    MemoryStream stream = new MemoryStream(1024);
    CookingInterface.InitCooking();

    if (CookingInterface.CookConvexMesh(convexMeshDesc, stream))
    {
	stream.Seek(0, SeekOrigin.Begin);
	ConvexMesh convexMesh = physics.CreateConvexMesh(stream);
	convexMeshShapeDesc = new ConvexShapeDesc(convexMesh);
	CookingInterface.CloseCooking();
    }

    convexMeshDesc.UnpinAll();
    return convexMeshShapeDesc;
}
{CODE}

Secondly, we have a triangle mesh shape that will detect collisions with every triangle in the shape. Unfortunately, it's very intensive on the physics engine to detect these kinds of collisions so there are a few restrictions. The most important one is that this can only be applied to static objects in your game world. The second is that they should have a reasonably low triangle count. Generally this is okay for a rooms with walls, floors, hallways, and so on. For the detailed shapes though you'll want to bound them with groups of simple shapes like spheres and boxes.

{CODE(wrap="1", colors="c#")}
public TriangleMeshShapeDesc CreateTriangleMesh(StaticMeshData meshData)
{
    // create descriptor for triangle mesh
    TriangleMeshShapeDesc triangleMeshShapeDesc = null;
	    TriangleMeshDesc triangleMeshDesc = new TriangleMeshDesc();
    triangleMeshDesc.PinPoints<float>(meshData.Points, 0, sizeof(float) * 3);
    triangleMeshDesc.PinTriangles<uint>(meshData.Indices, 0, sizeof(uint) * 3);
    triangleMeshDesc.VertexCount = (uint)meshData.Vertices.Length;
    triangleMeshDesc.TriangleCount = (uint)meshData.TriangleCount;

    MemoryStream stream = new MemoryStream(1024);
    CookingInterface.InitCooking();

    if (CookingInterface.CookTriangleMesh(triangleMeshDesc, stream))
    {
	stream.Seek(0, SeekOrigin.Begin);
	TriangleMesh triangleMesh = physics.CreateTriangleMesh(stream);
	triangleMeshShapeDesc = new TriangleMeshShapeDesc(triangleMesh);
	CookingInterface.CloseCooking();
    }

    triangleMeshDesc.UnpinAll();
    return triangleMeshShapeDesc;
}
{CODE}

If you need help, open a thread in [http://www.ogre3d.org/addonforums/viewforum.php?f=8|Mogre add-ons forum] and ask user [http://www.ogre3d.org/addonforums/memberlist.php?mode=viewprofile&u=9599|zarifus] to answer in this thread.


!See also
* ((NxOgre)) - Wiki page of the Ogre wrapper for PhysX, which contains useful information.
* [http://en.wikipedia.org/wiki/PhysX|PhysX at Wikipedia]
* [http://developer.nvidia.com/object/physx.html|PhysX official webiste] by Nvidia
* More example code - http://www.stigatle.net/index.php/mogre/71-mogrephysx
* [http://developer.nvidia.com/object/physx_dcc_plugins.html|PhysX DCC Plug-Ins] for ''3ds Max'' and ''Maya'' by Nvidia - Export objects/scenes to PhysX file format (XML) and load them by Mogre.
* [http://www.ogre3d.org/forums/viewtopic.php?f=11&t=59063|beastie] - A collision detection library for Ogre (without other depencies than Ogre)
* [http://knol.google.com/k/introduction-to-the-nvidia-physx-api#|Introduction to the Nvidia PhysX API] - A small (but very informative) article focusing on how to set up Physx scene

__Alternatives__
Here are alternatives for physics and collision detection with Mogre.
* ((MogreNewt))
* ((BulletSharp))
History: PhysX Candy Wrapper

Source of version: 22 (current)

Search by Tags

Latest Changes

Search

Online Users
