# Collision primitives

## Contents

# About

The collision primitives describe the shape of the objects. It doesn't describe its mass or weight distribution, just an overal shape good for collision detection. The mass and inertia is given by a body object (NewtonBody). So you can, for example, have a body with a mass and inertia torque like a box and (collision) shape like cylinder (or a "vehicle", or...), even if it may be pointles...

Collision primitives are reference counted objects. The application should call NewtonReleaseCollision in order to release references to the object. Neglecting to release references to collision primitives is a common cause of memory leaks.

Collision primitives can be reused with more than one body. This will reduce the amount of memory used be the engine, as well as speed up some calculations.

# Generic collision types

Newton supports a large variety of different collision primitives and you can even define your own collision primitive types. Usually you build up your scene using the generic collision primitives. However, to choose the right collision type for a particular purpose you have to consider the performance and quality of these primitives. The following diagram can help making a decision:

# Common functions

Generic collisions library functions:

NewtonCollisionCollideContinue

# Sphere

**Description**

Sphere collisions are generalized ellipsoids, the application can create many different kind of objects by just playing with dimensions of the radius. For example, to make a sphere, set all three radius to the same value. To make an ellipse of revolution, just set two of the three radius to the same value.

General ellipsoids are very good hull geometries to represent the outer shell of avatars in a game.

**Functions**

# Box

**Description**

A standard box primitive.

**Functions**

# Capsule

**Description**

The capsule height must be greater than or equal to the diameter of the cap. If this is not the case, then the height will be clamped to the diameter. Capsule is aligned with the x axis after creation.

**Functions**

# Cylinder

**Description**

A cylinder of given radius and height. Is aligned with the x axis after creation.

**Functions**

# Cone

**Description**

A cone of given radius and height. Is aligned with the x axis after creation.

The cone height must be greater than or equal to the diameter of the cap. If this is not the case, then the height will be clamped to the diameter.

**Functions**

# Chamfer Cylinder

A chamfer cylinder of given radius and height. The rotational axis is aligned with the x axis after creation.

**Functions**

# Null primitive

**Description**

Sometimes the application needs to create helper rigid bodies that will never collide with other bodies, for example the neck of a rag doll, or an internal part of an articulated structure. This can be done by using the material system but it too much work and it will increase unnecessarily the material count, and therefore the project complexity. The Null collision is a collision object that satisfy all this conditions without having to change the engine philosophy.

**Functions**

# Compound

**Description**

A container to hold an array of convex collision primitives.

Compound collision supports creation of complex concave primitives built out of convex shapes.

Compound collision primitives can only be made of convex collision primitives and they can not contain more compound collisions.

**Functions**

# Convex Hull

[The image is just for illustration what convex object means]

**Description**

A Convex Hull primitive for collision from a cloud of points.

Convex hulls are the solution to collision geometries that can not be easily represented by an implicit solid. The implicit solid primitives (spheres, cubes, cylinders, capsules, cones, etc.), have constant time complexity for contact calculation and are also extremely efficient on memory usage, therefore the application get perfect smooth behavior. However, in cases where the shape is too difficult or a polygonal representation is desired convex hulls are the ultimate solution. For example: it is ill-advised to model a 10000 point sphere as a convex hull, when the perfect sphere is available.

There is not upper limit as to how many vertex the application can pass to Newton to make a hull shape, however for performance and memory usage concern it is the application responsibility to keep the max vertex at the possible minimum. The minimum number of vertex should be equal or larger than 4 and it is the application responsibility that the points are part of a solid geometry.

Unpredictable results will occur if all points happen to be collinear or coplanar.

[note: the image is just for illustration what convex object means]

**Functions**

NewtonCreateConvexHullModifier

NewtonConvexHullModifierGetMatrix

NewtonConvexHullModifierSetMatrix

NewtonConvexCollisionSetUserID

NewtonConvexCollisionGetUserID

NewtonConvexCollisionCalculateVolume

NewtonConvexCollisionCalculateInertialMatrix

# User Mesh

[todo: image]

**Description**

UserMeshCollision provides the application with a method of overloading the built-in collision system for background objects.

UserMeshCollision can be used for implementing collisions with height maps, collisions with BSP, and any other collision structure the application supports and wishes to preserve. However, UserMeshCollision can not take advantage of the efficient and sophisticated algorithms and data structures of the built-in TreeCollision. We suggest you experiment with both methods and use the method best suited to your situation.

When a UserMeshCollision is assigned to a body, the mass of the body is ignored in all dynamics calculations. This make the body behave as a static body.

The most significant bit of a triangle index list is use to indite to Newton that edge between that index and next index is not part of collision calculation. The application can use this feature to mark concave and coplanar shared edges as non collidables. for example is two triangles has indices 1, 2, 3 and 3, 2, 4 respective, if the two triangle are coplanar, then the application can mark edge 2, 3 as: 1, 2 | 0x80000000, 3 | 0x80000000 for triangle 1 and 3 | 0x80000000, 2 | 0x80000000, 4 for the second triangle. these feature greatly enhances the quality of contact generation meshes with flat and concave faces.

**Functions**

# Tree collision

[todo: image]

**Description**

TreeCollision is the preferred method within Newton for collision with polygonal meshes of arbitrary complexity. The mesh must be made of flat non-intersecting polygons, but they do not explicitly need to be triangles. TreeCollision can be serialized by the application to/from an arbitrary storage device.

When a TreeCollision is assigned to a body the mass of the body is ignored in all dynamics calculations. This makes the body behave as a static body.

**Functions**

NewtonCreateTreeCollisionFromSerialization

NewtonTreeCollisionGetFaceAtribute

NewtonTreeCollisionSetFaceAtribute

# Height field collision

**Description**

HeightFieldCollision is the preferred method within Newton for collision used as height fields. You can use also TreeCollision to represent height field, however, HeightFieldCollision is not just much more efficient for this purpose, but also eliminates some artifacts arising from using a triangle soup for height field.

When a HeightFieldCollision is assigned to a body the mass of the body is ignored in all dynamics calculations. This makes the body behave as a static body.

**Functions**

NewtonCreateHeightFieldCollision

# Scene collision

**Description**

SceneCollision is the preferred method within Newton to represent the static environment of the scene. It actually acts as a wrapper for other collision primitives without the need to create bodies for these collisions. SceneCollision not just provides better architecture for your static environment, but it's also more efficient and uses less memory.

When a SceneCollision is assigned to a body the mass of the body is ignored in all dynamics calculations. This makes the body behave as a static body.

**Functions**

NewtonSceneCollisionCreateProxy