Newton Dynamics reference

| Newton.Dynamics: | Types | Modinfo | Source |

# Newton Dynamics

## Types Summary

TNBody | Creates a rigid body.
TNCollision |
TNMatrix |
TNMesh |
TNRayCastDelegate | A helper delegate for handling ray casts.
TNTreeCollision | A complex collision geometry tree.
TNWorld |

## Types

Type TNBody
Description | Creates a rigid body.
Information | Can be subclassed in order to override callbacks such as OnForceAndTorque().

Methods Summary
AddForce | Adds the net force applied to a rigid body.
AddTorque | Adds the net torque applied to a rigid body.
CalculateInverseDynamicsForce | Calculates the next force that net to be applied to the body to archive the desired velocity in the current time step.
Destroy |
GetAngularDamping | Gets the angular viscous damping of the body.
GetCentreOfMass | Gets the relative position of the center of mass of a rigid body.
GetCollidable | Returns true if the body is collidable.
GetForce | Gets the net force applied to a rigid body after the last Newton Update.
GetForceAcc | Gets the force applied on the last call to OnForceAndTorque/apply force and torque callback.
GetInertiaMatrix |
GetInvInertiaMatrix |
GetInvMass |
GetMassMatrix | Gets the mass matrix of a rigid body.
GetMatrix | Gets the transformation matrix of a rigid body, populating matrix.
GetOmega | Gets the global angular velocity of the body.
GetRotation | Gets the rotation part of the transformation matrix of a body, in form of a unit quaternion.
GetTorque | Gets the net torque applied to a rigid body after the last Newton Update.
GetTorqueAcc | Gets the torque applied on the last call to OnForceAndTorque/apply force and torque callback.
GetType | Returns the body type.
GetVelocity | Gets the global linear velocity of the body.
NewtonBodyGetAABB | Gets the world axis aligned bounding box (AABB) of the body.
OnForceAndTorque |
SetAngularDamping | Applies the angular viscous damping coefficient to the body.
SetCollidable | Sets the collidable state for the body.
SetForce | Sets the net force applied to a rigid body.
SetForceAndTorqueCallback | Assigns an event function for applying external force and torque to a rigid body.
SetLinearDamping | Applies the linear viscous damping coefficient to the body.
SetMassProperties |
SetMatrix | Sets the transformation matrix of a rigid body.
SetOmega | Sets the global angular velocity of the body.
SetTorque | Sets the net torque applied to a rigid body.
SetTransformCallback | Assign a transformation event function to the body.
SetVelocity | Sets the global linear velocity of the body.

Method AddForce(fx:Float, fy:Float, fz:Float)
Description | Adds the net force applied to a rigid body.
Information | This method is only effective when called from OnForceAndTorque/apply force and torque callback.

Method AddTorque(tx:Float, ty:Float, tz:Float)
Description | Adds the net torque applied to a rigid body.
Information | This method is only effective when called from OnForceAndTorque/apply force and torque callback.

Method CalculateInverseDynamicsForce(timestep:Float, vx:Float, vy:Float, vz:Float, fx:Float Var, fy:Float Var, fz:Float Var)
Description | Calculates the next force that net to be applied to the body to archive the desired velocity in the current time step.
Information | Can be useful when creating object for game play. This treats the body as a point mass and is uses the solver to calculates the net force that need to be applied to the body such that it reaches the desired velocity in the net time step.

Method Destroy()

Method GetAngularDamping(aX:Float Var, aY:Float Var, aZ:Float Var)
Description | Gets the angular viscous damping of the body.

Method GetCentreOfMass(cx:Float Var, cy:Float Var, cz:Float Var)
Description | Gets the relative position of the center of mass of a rigid body.
Information | This method can be used to set the relative offset of the center of mass of a rigid body. when a rigid body is created the center of mass is set the the point c(0, 0, 0), and normally this is the best setting for a rigid body. However there are situations in which and object does not have symmetry or simple some kind of special effect is desired, and this origin needs to be changed.

Method GetCollidable:Int()
Description | Returns true if the body is collidable.

Method GetForce(fx:Float Var, fy:Float Var, fz:Float Var)
Description | Gets the net force applied to a rigid body after the last Newton Update.

Method GetForceAcc(fx:Float Var, fy:Float Var, fz:Float Var)
Description | Gets the force applied on the last call to OnForceAndTorque/apply force and torque callback.
Information | This method can be useful to modify force from joint callback.

Method GetInertiaMatrix(matrix:TNMatrix)

Method GetInvInertiaMatrix(matrix:TNMatrix)

Method GetInvMass(mass:Float Var, Ixx:Float Var, Iyy:Float Var, Izz:Float Var)

Method GetMassMatrix(mass:Float Var, Ixx:Float Var, Iyy:Float Var, Izz:Float Var)
Description | Gets the mass matrix of a rigid body.

Method GetMatrix(matrix:TNMatrix)
Description | Gets the transformation matrix of a rigid body, populating matrix.

Method GetOmega(ox:Float Var, oy:Float Var, oz:Float Var)
Description | Gets the global angular velocity of the body.

Method GetRotation(q0:Float Var, q1:Float Var, q2:Float Var, q3:Float Var)
Description | Gets the rotation part of the transformation matrix of a body, in form of a unit quaternion.
Information | The rotation quaternion is the same as what the application would get by using at function to extract a quaternion form a matrix. however since the rigid body already contained the rotation in it, it is more efficient to just call this method avoiding expensive conversion.

Method GetTorque(tx:Float Var, ty:Float Var, tz:Float Var)
Description | Gets the net torque applied to a rigid body after the last Newton Update.

Method GetTorqueAcc(tx:Float Var, ty:Float Var, tz:Float Var)
Description | Gets the torque applied on the last call to OnForceAndTorque/apply force and torque callback.
Information | This method can be useful to modify torque from joint callback.

Method GetType:Int()
Description | Returns the body type.
Information | Returns one of NEWTON_DYNAMIC_BODY, NEWTON_KINEMATIC_BODY or NEWTON_DEFORMABLE_BODY.

Method GetVelocity(vx:Float Var, vy:Float Var, vz:Float Var)
Description | Gets the global linear velocity of the body.

Method NewtonBodyGetAABB(p0x:Float Var, p0y:Float Var, p0z:Float Var, p1x:Float Var, p1y:Float Var, p1z:Float Var)
Description | Gets the world axis aligned bounding box (AABB) of the body.

Method OnForceAndTorque(timestamp:Float, threadIndex:Int)

Method SetAngularDamping(aX:Float, aY:Float, aZ:Float)
Description | Applies the angular viscous damping coefficient to the body.
Information | The default value of *angularDamp* is clamped to a value between 0.0 and 1.0; the default value is 0.1, There is a non zero implicit attenuation value of 0.0001 assumed by the integrator. The dampening viscous friction torque is added to the external torque applied to the body every frame before going to the solver-integrator. This torque is proportional to the square of the magnitude of the angular velocity to the body in the opposite direction of the angular velocity of the body. An application can set *angularDamp* to zero when the to take control of the external forces and torque applied to the body, should the application desire to have absolute control of the forces over that body. However, it is recommended that the *linearDamp* coefficient be set to a non-zero value for the majority of background bodies. This saves the application from needing to control these forces and also prevents the integrator from adding very large velocities to a body.

Method SetCollidable(collidableState:Int)
Description | Sets the collidable state for the body.

Method SetForce(fx:Float, fy:Float, fz:Float, fw:Float)
Description | Sets the net force applied to a rigid body.
Information | This method is only effective when called from OnForceAndTorque/apply force and torque callback.

Method SetForceAndTorqueCallback(callback(body:TNBody, timestamp:Float, threadIndex:Int))
Description | Assigns an event function for applying external force and torque to a rigid body.
Information | The default is to call the OnForceAndTorque() method, which can be overriden by subclassing TNBody and re-implementing the method. The callback is called by the Newton Engine every time an active body is going to be simulated. The Newton Engine does not call the callback for bodies that are inactive or have reached a state of stable equilibrium.

Method SetLinearDamping(linearDamp:Float)
Description | Applies the linear viscous damping coefficient to the body.
Information | The default value of linearDamp is clamped to a value between 0.0 and 1.0; the default value is 0.1, There is a non zero implicit attenuation value of 0.0001 assume by the integrator.

Method SetMassProperties(mass:Float, collision:TNCollision)

Method SetMatrix(matrix:TNMatrix)
Description | Sets the transformation matrix of a rigid body.
Information | The application should make sure the transformation matrix has not scale, otherwise unpredictable result will occur.

Method SetOmega(ox:Float, oy:Float, oz:Float, ow:Float)
Description | Sets the global angular velocity of the body.

Method SetTorque(tx:Float, ty:Float, tz:Float, tw:Float)
Description | Sets the net torque applied to a rigid body.
Information | This method is only effective when called from OnForceAndTorque/apply force and torque callback.

Method SetTransformCallback(callback(body:TNBody, matrix:Float Ptr, threadIndex:Int))
Description | Assign a transformation event function to the body.
Information | The default is to call the OnTransform() method, which can be overriden by subclassing TNBody and re-implementing the method. The callback is called by the Newton engine every time a visual object that represents the rigid body has changed. The Newton engine does not call the callback for bodies that are inactive or have reached a state of stable equilibrium.

Method SetVelocity(vx:Float, vy:Float, vz:Float, vw:Float)
Description | Sets the global linear velocity of the body.

Type TNCollision

Type TNMatrix

Methods Summary
GetEulerAngles |

Functions Summary
GetIdentityMatrix |

Method GetEulerAngles(pitch0:Float Var, yaw0:Float Var, roll0:Float Var, pitch1:Float Var, yaw1:Float Var, roll1:Float Var)

Function GetIdentityMatrix:TNMatrix()

Type TNMesh

Methods Summary
AddFace |
ApplyBoxMapping |
ApplyCylindricalMapping |
ApplySphericalMapping |
ApplyTransform |
BeginFace |
CalculateOOBB |
CalculateVertexNormals |
Destroy |
EndFace |
FixTJoints |
GetNormalArray |
GetPointArray |
GetPointCount |
GetPointStrideInByte |
GetTotalFaceCount |
GetTotalIndexCount |
GetUV0Array |
GetUV1Array |
GetVertexCount |
GetVertexStrideInByte |
IsOpenMesh |
MeshGetVertexArray |
Polygonize |
Triangulate |

Method AddFace(vertexCount:Int, vertex:Float Ptr, strideInBytes:Int, materialIndex:Int)

Method ApplyBoxMapping(front:Int, side:Int, top:Int)

Method ApplyCylindricalMapping(cylinderMaterial:Int, capMaterial:Int)

Method ApplySphericalMapping(material:Int)

Method ApplyTransform(matrix:TNMatrix)

Method BeginFace()

Method CalculateOOBB(matrix:TNMatrix, x:Float Var, y:Float Var, z:Float Var)

Method CalculateVertexNormals(angle:Float)

Method Destroy()

Method EndFace()

Method FixTJoints()

Method GetNormalArray:Double Ptr()

Method GetPointArray:Double Ptr()

Method GetPointCount:Int()

Method GetPointStrideInByte:Int()

Method GetTotalFaceCount:Int()

Method GetTotalIndexCount:Int()

Method GetUV0Array:Double Ptr()

Method GetUV1Array:Double Ptr()

Method GetVertexCount:Int()

Method GetVertexStrideInByte:Int()

Method IsOpenMesh:Int()

Method MeshGetVertexArray:Double Ptr()

Method Polygonize()

Method Triangulate()

Type TNRayCastDelegate
Description | A helper delegate for handling ray casts.

Fields Summary
prefilter

Methods Summary
OnFilter |
OnPreFilter |

Field prefilter:Int = False
Description | Whether or not to enable the prefilter delegation.
Information | If prefilter is True, Newton will call OnPreFilter() right before executing the intersections between the ray and the primitive. If the method returns zero, Newton will not ray cast the primitive. The application can use this implement faster or smarter filters when implementing complex logic, otherwise for normal all ray cast this setting can be False.

Method OnFilter:Float(body:TNBody, shapeHit:TNCollision, hitContact:Float Ptr, hitNormal:Float Ptr, intersectParam:Float)
Information | The most common use for the ray cast function is the closest body hit. In this case it is important, for performance reasons, that the OnFilter() method returns the intersection parameter. If the OnFilter() method returns a value of zero the ray cast will terminate immediately.

Method OnPreFilter:Int(body:TNBody, collision:TNCollision)

Type TNTreeCollision Extends TNCollision
Description | A complex collision geometry tree.
Information | TNTreeCollision 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.

Methods Summary
AddFace | Adds an individual polygon to the TNTreeCollision.
EndBuild | Finalizes the construction of the polygonal mesh.

Method AddFace(vertexCount:Int, vertexPtr:Float Ptr, strideInBytes:Int, faceAttribute:Int)
Description | Adds an individual polygon to the TNTreeCollision.

Method EndBuild(optimize:Int)
Description | Finalizes the construction of the polygonal mesh.
Information | After the application has finished adding polygons to the TNTreeCollision, it must call this method to finalize the construction of the collision mesh. If concave polygons are added to the *TreeCollision*, the application must call this function with the parameter *optimize* set to 1. With the *optimize* parameter set to 1, Newton will optimize the collision mesh by removing non essential edges from adjacent flat polygons. Newton will not change the topology of the mesh but significantly reduces the number of polygons in the mesh. The reduction factor of the number of polygons in the mesh depends upon the irregularity of the mesh topology. A reduction factor of 1.5 to 2.0 is common. Calling this method with the parameter *optimize* set to zero, will leave the mesh geometry unaltered.

Type TNWorld

Methods Summary
CreateBox | Creates a box primitive for collision.
CreateCylinder | Creates a cylinder primitive for collision.
CreateDynamicBody | Creates a rigid body.
CreateMesh |
CreateSphere | Creates a generalized ellipsoid primitive.
CreateTreeCollision | Creates an empty complex collision geometry tree.
Destroy |
GetBodyCount | Returns the total number of rigid bodies in the world.
GetConstraintCount | Returns the total number of constraints in the world.
InvalidateCache | Resets all internal states of the engine.
RayCast | Shoots a ray from p0 to p1 and calling the delegate's OnFilter/OnPreFilter with each ray intersection.
SetContactMergeTolerance | Sets the contact merge tolerance.
SetFrictionModel | Sets coulomb model of friction.
SetMinimumFrameRate | Sets the minimum frame rate at which the simulation can run.
Update | Advances the simulation by an amount of time.

Functions Summary
Create | Creates an instance of the Newton world.

Method CreateBox:TNCollision(dx:Float, dy:Float, dz:Float, shapeID:Int = 0, offsetMatrix:TNMatrix = Null, custom:TNCollision = Null)
Description | Creates a box primitive for collision.

Method CreateCylinder:TNCollision(radius:Float, height:Float, shapeID:Int = 0, offsetMatrix:TNMatrix = Null, custom:TNCollision = Null)
Description | Creates a cylinder primitive for collision.

Method CreateDynamicBody:TNBody(collision:TNCollision, matrix:TNMatrix, custom:TNBody = Null)
Description | Creates a rigid body.
Information | Creates a Newton rigid body and assigns a the collision geometry representing the rigid body. Optionally pass a subclassed TNBody object for direct access to force/torque callbacks.

Method CreateMesh:TNMesh()

Method CreateSphere:TNCollision(radius:Float, shapeID:Int = 0, offsetMatrix:TNMatrix = Null, custom:TNCollision = Null)
Description | Creates a generalized ellipsoid primitive.
Information | Sphere collision 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 tree radius to the same value, to make a ellipse of revolution just set two of the tree radius to the same value.

Method CreateTreeCollision:TNTreeCollision(shapeID:Int = 0, custom:TNTreeCollision = Null)
Description | Creates an empty complex collision geometry tree.

Method Destroy()

Method GetBodyCount:Int()
Description | Returns the total number of rigid bodies in the world.

Method GetConstraintCount:Int()
Description | Returns the total number of constraints in the world.

Method InvalidateCache()
Description | Resets all internal states of the engine.
Information | When an application wants to reset the state of all the objects in the world to a predefined initial condition, just setting the initial position and velocity is not sufficient to reproduce equal runs since the engine maintain there are internal states that in order to take advantage of frame to frame coherence. In this cases this method will reset all of the internal states.

Method RayCast(p0x:Float, p0y:Float, p0z:Float, p1x:Float, p1y:Float, p1z:Float, delegate:TNRayCastDelegate, threadIndex:Int = 0)
Description | Shoots a ray from p0 to p1 and calling the delegate's OnFilter/OnPreFilter with each ray intersection.
Information | The ray cast will call the application with each body intersecting the line segment. By writing the OnFilter() in different ways the application can implement different flavors of ray casting. For example an all body ray cast can be easily implemented by having the OnFilter() always returning 1.0, and copying each rigid body into an array/list; a closest hit ray cast can be implemented by saving the body with the smaller intersection parameter and returning the parameter t; and a report the first body hit can be implemented by having the filter returning zero after the first call and saving the rigid body.

Method SetContactMergeTolerance(tolerance:Float)
Description | Sets the contact merge tolerance.

Method SetFrictionModel(model:Int)
Description | Sets coulomb model of friction.

Information

Allows the application to chose between and exact or an adaptive coulomb friction model.

0: Is the exact model. Friction forces are calculated in each frame. This model is good for applications where precision is more important than speed, ex: realistic simulation.

1: Is the adaptive model. Here values from previous frames are used to determine the maximum friction values of the current frame. This is about 10% faster than the exact model however it may introduce strange friction behaviors. For example a bouncing object tumbling down a ramp will act as a friction less object because the contacts do not have continuity. In general each time a new contact is generated the friction value is zero, only if the contact persist a non zero friction values is used. The second effect is that if a normal force is very strong, and if the contact is suddenly destroyed, a very strong friction force will be generated at the contact point making the object react in a non-familiar way.

Method SetMinimumFrameRate(framerate:Float)
Description | Sets the minimum frame rate at which the simulation can run.
Information | The default minimum frame rate of the simulation is 60 frame per second. When the simulation falls below the specified minimum frame, Newton will perform sub steps in order to meet the desired minimum FPS.

Method Update(timestep:Float)
Description | Advances the simulation by an amount of time.
Information | The Newton Engine does not perform sub-steps, and does not need tuning parameters. It is the responsibility of the application to ensure that timestep is small enough to guarantee physics stability.

Function Create:TNWorld()
Description | Creates an instance of the Newton world.

## Module Information

Version | 1.00
License | zlib
Copyright | Newton Dynamics - 2003-2011 Julio Jerez and Alain Suero
Copyright | Wrapper - 2015-2016 Bruce A Henderson
History | 1.00
History | Initial Release.
CC_OPTS | -D_NEWTON_STATIC_LIB
CC_OPTS | -DPTW32_BUILD -DPTW32_STATIC_LIB -D_MINGW_32_VER
CC_OPTS | -msse -msse3 -mfpmath=sse -ffloat-store -ffast-math -freciprocal-math -funsafe-math-optimizations -fsingle-precision-constant
CC_OPTS | -DPTW32_BUILD -DPTW32_STATIC_LIB -D_MINGW_64_VER
CC_OPTS | -msse -msse3 -mfpmath=sse -ffloat-store -ffast-math -freciprocal-math -funsafe-math-optimizations -fsingle-precision-constant
CC_OPTS | -D_MACOSX_VER -msse4.1
CC_OPTS | -O2 -msse -msse3
CC_OPTS | -D_POSIX_VER -mfpmath=sse -ffloat-store -ffast-math -freciprocal-math -funsafe-math-optimizations -fsingle-precision-constant
CC_OPTS | -O2 -msse -msse3
CC_OPTS | -D_POSIX_VER_64 -mfpmath=sse -ffloat-store -ffast-math -freciprocal-math -funsafe-math-optimizations -fsingle-precision-constant
CC_OPTS | -D_POSIX_VER -ffloat-store -ffast-math -freciprocal-math -funsafe-math-optimizations -fsingle-precision-constant