From Newton Wiki
Jump to: navigation, search



NewtonCollision* NewtonCreateConvexHull (const NewtonWorld* const newtonWorld, int count, const dFloat* const vertexCloud, int strideInBytes, dFloat tolerance, int shapeID, const dFloat* const offsetMatrix)


Create a Convex Hull object.


  • const NewtonWorld *newtonWorld - pointer to the Newton world.
  • int count - number of points/vertices sent in vertexCloud (must be at least 4).
  • const dFloat* vertexCloud - pointer to the first element of an array of points/vertices.
  • int strideInBytes - vertex size in bytes, must be at least 12.
  • dFloat tolerance - the vertex optimization tolerance. A higher number means the hull can be simplified where there are multiple vertices with distance lower than the tolerance; this is useful when generating simpler convex hulls from highly detailed meshes.
  • int shapeID
  • const dFloat *offsetMatrix - pointer to the first element of an array of 16 floats containing the offset matrix of the box relative to the body. If this parameter is NULL, then the primitive is centered at the origin of the body.


  • pointer to the convex hull


Creates a ConvexHull primitive for collision from a cloud of points.


  • Convex hulls are the solution to collision primitives that cannot 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 shows perfectly smooth behavior. However for cases where the shape is too complex or a polygonal representation is desired convex hulls are the ultimate solution. For example it is a mistake to model a 10000 point sphere as a convex hull, when the perfect sphere is available.
  • There is no upper limit as to how many vertices the application can pass to Newton to make a hull shape, however for performance and memory usage concerns it is the application's responsibility to keep the vertex count as low as possible. The minimum number of vertices should be equal to or greater than 4 and it is the application's responsibility to ensure the points are part of a solid geometry. Unpredictable results will occur if all points happen to be collinear or coplanar.
  • 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.

The tolerance parameter

It's new since Newton 2 and can speed up the performance by reducing the count of vertices of a convex hull.

Here is the description by Julio Jerez (author of Newton):

The convex hull tolerance does not always apply and it is hard to predict, say for example you have a box, then the parameter will do nothing because adjacent plane bend 90 degree.

Say some body have a cube with bevel edges, the at the corner you will have many points that are very close to each other this result on a convex hull that is very dense on the edges and the vertex.

In that case the tolerance parameter does make a difference. What is does is that after the Hull is made, for each vertex, an average plane is created by fanning of all the vertices that can be reach from a direct edge going out of that vertex.

If the distance from each vertex to the average plane is very small,
And the distance from the center vertex to the plane is smaller than the tolerance,
Then the center vertex can be extracted from the hull and the hull can be reconstructed,
The resulting shape will not be too different from the ideal one.
It continues doing that until not more vertex can be subtracted from the original shape.

Basically what is does is that is remove lots of vertices that are too close and make the shep to dense for collision.

A tolerance of 0.002 is good candidate especially when you have large cloud of vertices because it will eliminate points that are a 2 millimeter of less from the ideal hull, It leads to a great speed up in collision time.

(additional note: this value depends to the kind of application and their dimensions)

Since Newton 2.25 the tolerance depend of the diagonal of the cloud point (or bounding box). Ex: A prism with large and small dimension (580 x 0.5 x 580) will have a large diagonal (820). If you set tolerance at 0.001 then the function will eliminate point that are less close of 820*0.001=0.8 units. So your prism become a plane and the function return NULL. To resolve this error just set a lower tolerance. This change was made to get same shape for hull with different scale.

See also

NewtonReleaseCollision NewtonCreateConvexHullModifier Newton SDK API reference#Category:convex_collision_primitives_creation_functions

Keywords (for better search results):
create convex hull createhull convexhull collision detection