Newton Game Dynamics 1.5

Create an instance of the Newton world.

Parameters

NewtonAllocMemory mallocFnt	-	is a pointer to the memory allocator callback function. If this parameter is NULL the standard malloc function is used.
NewtonFreeMemory mfreeFnt	-	is a pointer to the memory release callback function. If this parameter is NULL the standard free function is used.

Return

a pointer to an instance of the Newton world.

Remarks

this function must be called before any of the other API functions.

See also

NewtonDestroy, NewtonDestroyAllBodies

Destroy an instance of the Newton world.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world.

Return

Nothing.

Remarks

This function will destroy the entire Newton world.

See also

NewtonCreate, NewtonDestroyAllBodies

Get the global scale factor.

Remarks

the physics system in theory should be dimensionless, however in practice the engine have to be implemented with limited precision floating numbers and is also built for real-time simulation, it is inevitable that tolerances have to be used in order to increase performance, and reduce instabilities. These tolerances make the engine dimension dependent, for example let say a rigid body is considered at rest when its velocity is less than 0.01 units per second for some frames. For a program using meters as unit this translate to 0.01 meters per second, however for a program using centimeter this translate to 0.0001 meter per second, since the precession of speed is independent of the unit system, this means that in the second system the engine has to work much harder to bring the body to rest. A solution for this is to scale all tolerances to match the unit system. The argument globalScale must be a constant to convert the unit system in the game to meters, for example if in your game you are using 39 units is a meter, the globaScale must be 39. The exact conversion factor does not have to be exact, but the closer it is to reality the better performance the application will get. Applications that are already using meters as the unit system must pass 1.0 as globalScale.

See also

NewtonCreate dFloat NewtonGetGlobalScale(const NewtonWorld* newtonWorld) { Newton *world; world = (Newton *) newtonWorld; return world->GetGlobalScale(); return dgFloat32(1.0f); }

Set the current platform hardware architecture.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int model	-	model of operation 0 = default, 1 = medium, n = best.

Return

Nothing

Remarks

This function allows the application to configure the Newton to take advantage for specific hardware architecture in the same platform.

0

force the hardware lower common denominator for the running platform.

1

will try to use common floating point enhancement like spacial instruction set on the specific architecture. This mode made lead to result that differ from mode 1 and 2 as the accumulation round off errors maybe different.

2

the engine will try to use the best possible hardware setting found in the current platform this is the default configuration. This mode made lead to result that differ from mode 1 and 2 as the accumulation round off errors maybe different.

Remarks

the only hardware mode guarantee to work is mode 0. all other are only hints to the engine, for example setting mode 1 will take not effect on CPUs without specially floating point instructions set.

Set the solver precision mode.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int model	-	model of operation 0 = exact, 1 = adaptive, n = linear. The default is exact.

Return

Nothing

Remarks

This function allows the application to configure the Newton solver to work in three different modes.

0

Is the exact mode. This is good for application where precision is more important than speed, ex: realistic simulation.

1

Is the adaptive mode, the solver is not as exact but the simulation will still maintain a high degree of accuracy. This mode is good for applications were a good degree of stability is important but not as important as speed.

n

Linear mode. The solver will not try to reduce the joints relative acceleration errors to below some limit, instead it will perform up to n passes over the joint configuration each time reducing the acceleration error, but it will terminate when the number of passes is exhausted regardless of the error magnitude. In general this is the fastest mode and is is good for applications where speed is the only important factor, ex: video games.

Remarks

the adaptive friction model combined with the linear model make for the fastest possible configuration of the Newton solver. This setup is best for games. If you need the best realistic behavior, we recommend the use of the exact solver and exact friction model which are the defaults.

See also

NewtonSetFrictionModel

Set coulomb model of friction.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int model	-	friction model; 0 = exact coulomb, 1 = adaptive coulomb, The default is exact.

Return

Nothing.

Remarks

This function 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.

Remarks

the adaptive friction model combined with the linear model make for the fastest possible configuration of the Newton solver. This setup is best for games. If you need the best realistic behavior, we recommend the use of the exact solver and exact friction model which are the defaults.

See also

NewtonSetSolverModel

Advance the simulation by an amount of time.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
dFloat timestep	-	time step in seconds

Return

Nothing

Remarks

This function will advance the simulation by the amount of time specified by timestep. 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.

Set the minimum frame rate at which the simulation can run.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
dFloat frameRate	-	minimum frame rate of the simulation in frame per second. This value is clamped between 60fps and 1000fps

Return

nothing

Remarks

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.

Return the correct time step for this simulation update.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world.

Remark

This application can used this function to get the currect siulation time step.

Return

correct update timestep.

Remove all bodies and joints from the newton world.

Parameters

const NewtonWorld *newtonWorld

-

is a pointer to the Newton world

Return

Nothing

Remarks

This function will destroy all bodies and all joints in the Newton world, but it will retain group IDs. Use this function for when you want to clear the world but preserve all the group IDs and material pairs.

See also

NewtonMaterialDestroyAllGroupID

Set the size of the Newton world.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
const dFloat *minPtr	-	is the minimum point of the world bounding box
const dFloat *maxPtr	-	is the maximum point of the world bounding box

Return

Nothing.

Remarks

The Newton world must have a finite size. The size of the world is set to a box +- 100 units in all three dimensions at creation time and after a call to the function NewtonRemoveAllBodies

See also

NewtonSetBodyLeaveWorldEvent

Set the event callback function to be called in the event a body is escaping the limits of the world during simulation time.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
NewtonBodyLeaveWorld callback	-	is the pointer to the function callback

Return

Nothing

Remarks

When a body moves outside the bounding box that defines the world space the body is automatically disabled and Newton calls the application defined callback function NewtonBodyLeaveWorld callback. The application should decide how to handle the event, because Newton will make the callback once. The only options available to the application are: do nothing or destroy the object.

Remarks

if the application wants to reinitialize the body, it will have to used the function NewtonBodySetMatrixRecursive, this is because it is possible that the rigid body is part of a set of articulate bodies and only one part leave the world while the others are still inside the world volume, and in and situation like this the function NewtonSetMatrix will lead to unpredictable results.

See also

NewtonSetWorldSize, NewtonBodySetMatrixRecursive

Remove the body from the active simulation list.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
const NewtonBody *body	-	is the pointer to the body to be frozen

Return

Nothing.

Remarks

When a body is created it is automatically placed in the active simulation list. As an optimization for large scenes, you may use this function to put background bodies in an inactive equilibrium state.

Remarks

This function tells Newton that this body does not currently need to be simulated. However, if the body is part of a larger configuration it may be affected indirectly by the reaction forces of objects that it is connected to.

See also

NewtonWorldUnfreezeBody, NewtonBodySetAutoFreeze, NewtonBodyGetAutoFreeze

Add the body to the active simulation list.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
const NewtonBody *body	-	is the pointer to the body to be activated

Return

Nothing

Remarks

This function tells Newton to simulate the rigid body body.

See also

NewtonWorldFreezeBody, NewtonBodySetAutoFreeze, NewtonBodyGetAutoFreeze

Iterate thought every body in the world calling the function callback.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
NewtonBodyIterator callback	-	application define callback

Return

nothing

Remarks

The application can call this function to iterate thought every body in the world. the application should provide the function NewtonBodyIterator callback to be called by Newton for every body in the world

Remarks

this function affect severally the performance of Newton. The application should call this function only for debugging purpose See also: NewtonBodyForEachPolygonDo

Return the current library version number.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the newton world.

Return

release decimal three digit value x.xx the first digit: is mayor version number (interface changes among other things) the second digit: is mayor patch number (new features, and bug fixes) third digit: is minor bug fixed patch.

Store a user defined data value with the world.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the newton world.
void *userDataPtr	-	pointer to the user defined user data value.

Return

Nothing.

Remarks

The application can store a user defined value with the Newton world. The user data is useful for application developing object oriented classes based on the Newton API.

See also

NewtonWorldGetUserData

Retrieve a user previously stored user define value with the world.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world.

Return

user data value.

Remarks

The application can store a user defined value with the Newton world. The user data is useful for application developing object oriented classes based on the Newton API.

See also

NewtonWorldGetUserData

Shoot a ray from p0 to p1 and call the application callback with each ray intersection.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the world.
const dFloat *p0	-	pointer to an array of at least three floats containing the beginning of the ray in global space.
const dFloat *p1	-	pointer to an array of at least three floats containing the end of the ray in global space.
NewtonWorldRayFilterCallback filter	-	user define function to be called for each body hit during the ray scan.
void *userData	-	user data to be passed to the filter callback.

Return

nothing

Remarks

The ray cast function will call the application with each body intersecting the line segment. By writing the callback filter function 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 filter function always returning 1.0, and copying each rigid body into an array of pointers; 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 function returning zero after the first call and saving the pointer to the rigid body.

Remarks

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 filter function returns the intersection parameter. If the filter function returns a value of zero the ray cast will terminate immediately.

Remarks

The ray cast function is provided as an utility function, this means that even thought the function is very high performance by function standards, it can not by batched and therefore it can not be an incremental function. For example the cost of calling 1000 ray cast is 1000 times the cost of calling one ray cast. This is much different than the collision system where the cost of calculating collision for 1000 pairs in much, much less that the 1000 times the cost of one pair. Therefore this function must be used with care, as excessive use of it can degrade performance.

Get the value of the default MaterialGroupID.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world

Return

The ID number for the default Group ID.

Remarks

Group IDs can be interpreted as the nodes of a dense graph. The edges of the graph are the physics materials. When the Newton world is created, the default Group ID is created by the engine. When bodies are created the application assigns a group ID to the body.

Create a new MaterialGroupID.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world

Return

The ID of a new GroupID.

Remarks

Group IDs can be interpreted as the nodes of a dense graph. The edges of the graph are the physics materials. When the Newton world is created, the default Group ID is created by the engine. When bodies are created the application assigns a group ID to the body.

Note

The only way to destroy a Group ID after its creation is by destroying all the bodies and calling the function *NewtonMaterialDestroyAllGroupID*.

See also

NewtonMaterialDestroyAllGroupID

Remove all groups ID from the Newton world.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world

Return

Nothing.

Remarks

This function removes all groups ID from the Newton world. This function must be called after there are no more rigid bodies in the word.

See also

NewtonDestroyAllBodies

Set the material defined by the interaction between two physics groups to be collidable or non-collidable by default.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int id0	-	group id0
int id1	-	group id1
int state	-	state for this material: 1 = collidable; 0 = non collidable

Return

Nothing.

Set the material defined by the interaction between two physics groups to enable or desable continue collision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int id0	-	group id0
int id1	-	group id1
int state	-	state for this material: 1 = continue collision on; 0 = continue collision off, default mode is on

Return

Nothing.

Remarks

continue collision mode enable allow the engine to predict colliding contact on rigid bodies Moving at high speed of subject to strong forces.

Remarks

continue collision mode does not prevent rigid bodies from interpenetration instead it prevent bodies from passing trough each others by extrapolating contact points when the bodies normal contact calculation determine the bodies are not colliding.

Remarks

for performance reason the bodies angular velocities is only use on the broad face of the collision, but not on the contact calculation.

Remarks

continue collision does not perform back tracking to determine time of contact, instead it extrapolate contact by incrementally extruding the collision geometries of the two colliding bodies along the linear velocity of the bodies during the time step, if during the extrusion colliding contact are found, a collision is declared and the normal contact resolution is called.

Remarks

for continue collision to be active the continue collision mode must on the material pair of the colliding bodies as well as on at least one of the two colliding bodies.

Remarks

Because there is penalty of about 40% to 80% depending of the shape complexity of the collision geometry, this feature is set off by default. It is the job of the application to determine what bodies need this feature on. Good guidelines are: very small objects, and bodies that move a height speed.

See also

NewtonBodySetContinuousCollisionMode

Set the default coefficients of friction for the material defined by the interaction between two physics groups.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int id0	-	group id0
int id1	-	group id1
dFloat staticFriction	-	static friction coefients
dFloat kineticFriction	-	dynamic coefficient of friction

Return

Nothing.

Remarks

staticFriction and kineticFriction must be positive values. kineticFriction must be lower than staticFriction. It is recommended that staticFriction and kineticFriction be set to a value lower or equal to 1.0, however because some synthetic materials can have higher than one coeficient of friction Newton allows for the coeficient of friction to be as high as 2.0.

Set the default coefficients of restitution (elasticity) for the material defined by the interaction between two physics groups.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int id0	-	group id0
int id1	-	group id1
dFloat elasticCoef	-	static friction coefficients

Return

Nothing.

Remarks

elasticCoef must be a positive value. It is recommended that elasticCoef be set to a value lower or equal to 1.0

Set the default softness coefficients for the material defined by the interaction between two physics groups.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world
int id0	-	group id0
int id1	-	group id1
dFloat softnessCoef	-	softness coefficient

Return

Nothing.

Remarks

softnessCoef must be a positive value. It is recommended that softnessCoef be set to value lower or equal to 1.0 A low value for softnessCoef will make the material soft. A typical value for softnessCoef is 0.15

Set userData and the functions event handlers for the material defined by the interaction between two physics groups.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int id0	-	group id0.
int id1	-	group id1.
void *userData	-	user data value.
NewtonContactBegin beginCallback	-	address of the event function called before contact calculation for collision. This parameter can be NULL.
NewtonContactProcess processCallback	-	address of the event function called for every contact resulting from contact calculation. This parameter can be NULL.
NewtonContactEnd endCallback	-	address of the event function called after all contacts are processed. This parameter can be NULL.

Return

Nothing.

Remarks

When the AABB extend of the collision geometry of two bodies overlap, Newton collision system retrieves the material interaction that defines the behavior between the pair of bodies. The material interaction is collected from a database of materials, indexed by the material gruopID assigned to the bodies. If the material is tagged as non collidable, then no action is taken and the simulation continues. If the material is tagged as collidable, and a beginCallback was set for this material, then the beginCallback function is called. If the function *beginCallback* returns 0, no further action is taken for this material (this can be use to ignore the interaction under certain conditions). If the function *beginCallback* returns 1, Newton proceeds to calculate the array of contacts for the pair of colliding bodies. If the function processCallback was set, the application receives a callback for every contact found between the two colliding bodies. Here the application can perform fine grain control over the behavior of the collision system. For example, rejecting the contact, making the contact frictionless, applying special effects to the surface etc. After all contacts are processed and if the function endCallback was set, Newton calls endCallback. Here the application can collect information gathered during the contact-processing phase and provide some feedback to the player. A typical use for the material callback is to play sound effects. The application passes the address of structure in the userData along with three event function callbacks. When the function beginCallback is called by Newton, the application resets a variable say maximumImpactSpeed. Then for every call to the function processCallback, the application compares the impact speed for this contact with the value of maximumImpactSpeed, if the value is larger, then the application stores the new value along with the position, and any other quantity desired. When the application receives the call to endCallback the application plays a 3d sound based in the position and strength of the contact.

Get userData associated with this material.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int id0	-	group id0.
int id1	-	group id1.

Return

Nothing.

Disable processing for the contact.

Parameters

const NewtonMaterial materialHandle

-

pointer to a material pair

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Get the userData set by the application when it created this material pair.

Parameters

const NewtonMaterial materialHandle

-

pointer to a material pair

Return

Application user data.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Return the face attribute assigned to this face when for a user defined collision or a Newton collision tree.

Parameters

const NewtonMaterial materialHandle

-

pointer to a material pair

Return

face attribute for collision trees. Zero if the contact was generated by two convex collisions.

Remarks

This function can only be called from a material callback event handler.

Remarks

this function can be used by the application to retrieve the face id of a polygon for a collision tree.

See also

NewtonMaterialSetCollisionCallback

Get the current time step.

Parameters

const NewtonMaterial materialHandle

-

pointer to a material pair

Return

the current time step.

Remarks

This function can only be called from a material callback event handler. The function can be useful for the implementation of powered contacts.

See also

NewtonMaterialSetCollisionCallback

Calculate the speed of this contact along the normal vector of the contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair
const NewtonContact contactlHandle	-	pointer to the contact data

Return

Contact speed. A positive value means the contact is repulsive.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Calculate the speed of this contact along the tangent vector of the contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
const NewtonContact contactlHandle	-	pointer to the contact data.
int index	-	index to the tangent vector. This value can be 0 for primary tangent direction or 1 for the secondary tangent direction.

Return

Contact tangent speed.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Get the contact position and normal in global space.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat *positPtr,	-	pointer to an array of at least three floats to hold the contact position.
dFloat *normalPtr	-	pointer to an array of at least three floats to hold the contact normal.

Return

Nothing.

Remarks

This function can only be called from a material callback event handle.

See also

NewtonMaterialSetCollisionCallback

Get the contact force vector in global space.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat *forcePtr,	-	pointer to an array of at least three floats to hold the force vector in global space.

Return

Nothing.

Remarks

The contact force value is only valid when calculating resting contacts. This means if two bodies collide with non zero relative velocity, the reaction force will be an impulse, which is not a reaction force, this will return zero vector. this function will only return meaningful values when the colliding bodies are at rest.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Get the contact tangent vector to the contact point.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat *dir0	-	pointer to an array of at least three floats to hold the contact primary tangent vector.
dFloat *dir1	-	pointer to an array of at least three floats to hold the contact secondary tangent vector.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Retrieve a user defined value stored with a convex collision primitive.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
const NewtonBody *bodyPtr	-	is the pointer to the body.

Return

a user defined value. Zero if not id was stored with the collision primitive.

Remarks

the application can store an id with any collision primitive. This id can be used to identify what type of collision primitive generated a contact. This function can only be called from a contact callback,

Remarks

this function can only be called from a contact process callback. If called from contact callback begin this function will crash the application.

See also

NewtonConvexCollisionSetUserID, NewtonCreateBox, NewtonCreateSphere

Override the default softness value for the contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat softness	-	softness value, must be positive.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialSetDefaultSoftness

Override the default elasticity (coefficient of restitution) value for the contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat restitution	-	elasticity value, must be positive.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialSetDefaultElasticity

Enable or disable friction calculation for this contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
int state*	-	new state. 0 makes the contact frictionless along the index tangent vector.
int index	-	index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback

Override the default value of the static coefficient of friction for this contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat coef	-	static friction coeficient. Must be positive.
int index	-	index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

Return

nothing

Remarks

this function can only be called from a material callback event handler.

Remarks

It is recommended that coef be set to a value lower or equal to 1.0, however because some synthetic materials can have hight than one coeficient of friction Newton allows for the coeficient of friction to be as high as 2.0.

Remarks

the value coef will be clamped between the current kinetic friction and 2.0 (the maximum friction allowed). If the application wants to set a static friction lower than the current kinetic friction it must decrease the kinetic friction first.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialSetDefaultFriction, NewtonMaterialSetContactKineticFrictionCoef

Override the default value of the kinetic coefficient of friction for this contact.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat coef	-	static friction coefficient. Must be positive.
int index	-	index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

Remarks

It is recommended that coef be set to a value lower or equal to 1.0, however because some synthetic materials can have hight than one coeficient of friction Newton allows for the coeficient of friction to be as high as 2.0.

Remarks

the value coef will be clamped between 0.01f (minimum friction value) and that of the current static friction. If the application wants to set a kinetic friction higher than the current static friction it must increase the static friction first.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialSetDefaultFriction, NewtonMaterialSetContactStaticFrictionCoef

Force the contact point to have a non-zero acceleration aligned this the contact normal.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat accel	-	desired contact acceleration, Must be a positive value

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

Remarks

This function can be used for spacial effects like implementing jump, of explosive contact in a call back.

See also

NewtonMaterialSetCollisionCallback

Force the contact point to have a non-zero acceleration along the surface plane.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
dFloat accel	-	desired contact acceleration.
int index	-	index to the tangent vector. 0 for primary tangent vector or 1 for the secondary tangent vector.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialContactRotateTangentDirections

Set the new direction of the for this contact point.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
const dFloat *direction	-	pointer to an array of at least three floats holding the direction vector.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler. This function changes the basis of the contact point to one where the contact normal is alinend to the new direction vector and the tangent direction are recalculated to be perpendicular to teh new contact normal.

Remarks

In 99.9% of the cases the collision system can calculates a very good contact normal. however this algorithm that calculate the contact normal use as criteria the normal direction that will resolve the interpenetration with the least amount on motion. There are situations however when this solution is not the best. Take for example a rolling ball over a texelated floor, when the ball is over a flat polygon, the contact normal is always perpendicular to the floor and pass by the origin of the sphere, however when the sphere is going across two adjacent polygons, the contact normal is now perpendicular to the polygons edge and this does not guarantee they it will pass bay the origin of the sphere, but we know that the best normal is always the one passing by the origin of the sphere.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialContactRotateTangentDirections

Rotate the tangent direction of the contacts until the primary direction is aligned with the alignVector.

Parameters

const NewtonMaterial materialHandle	-	pointer to a material pair.
const dFloat *alignVector	-	pointer to an array of at least three floats holding the aligning vector.

Return

Nothing.

Remarks

This function can only be called from a material callback event handler. This function rotates the tangent vectors of the contact point until the primary tangent vector and the align vector are perpendicular (ex. when the dot product between the primary tangent vector and the alignVector is 1.0). This function can be used in conjunction with NewtonMaterialSetContactTangentAcceleration in order to create special effects. For example, conveyor belts, cheap low lod vehicles, slippery surfaces, etc.

See also

NewtonMaterialSetCollisionCallback, NewtonMaterialSetContactNormalDirection

Create a transparent collision primitive.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world.

Return

Pointer to the collision object.

Remarks

Some times 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.

Remarks

Collision primitives are reference counted objects. The application should call NewtonReleaseCollision in order to release references to the objects. 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 by the engine, as well as speed up some calculations.

See also

NewtonReleaseCollision

Create a box primitive for collision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat dx	-	box side one x dimension.
dFloat dy	-	box side one y dimension.
dFloat dz	-	box side one z dimension.
const dFloat *offsetMatrix	-	pointer to 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.

Return

Pointer to the box

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

Create a generalized ellipsoid primitive..

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat radiusX	-	sphere radius along x axis.
dFloat radiusY	-	sphere radius along x axis.
dFloat radiusZ	-	sphere radius along x axis.
const dFloat *offsetMatrix	-	pointer to an array of 16 floats containing the offset matrix of the sphere relative to the body. If this parameter is NULL then the sphere is centered at the origin of the body.

Return

Pointer to the generalized sphere.

Remarks

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.

Remarks

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

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

Create a cone primitive for collision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat radius	-	cone radius at the base.
dFloat height	-	cone height along the x local axis from base to tip.
const dFloat *offsetMatrix	-	pointer to 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.

Return

Pointer to the box

Remark

the cone height must equal of larger than the sum of the cap radius. if this is not the case the height will be clamped the 2 * radius.

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

Create a capsule primitive for collision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat radius	-	capsule radius at the base.
dFloat height	-	capsule height along the x local axis from tip to tip.
const dFloat *offsetMatrix	-	pointer to 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.

Return

Pointer to the box

Remark

the capsule height must equal of larger than the sum of the cap radius. If this is not the case the height will be clamped the 2 * radius.

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

Create a cylinder primitive for collision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat radius	-	cylinder radius at the base.
dFloat height	-	cylinder height along the x local axis.
const dFloat *offsetMatrix	-	pointer to 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.

Return

Pointer to the box

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

Create a ChamferCylinder primitive for collision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat radius	-	ChamferCylinder radius at the base.
dFloat height	-	ChamferCylinder height along the x local axis.
const dFloat *offsetMatrix	-	pointer to 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.

Return

Pointer to the box

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

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

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat count	-	number of consecutive point to follow must be at least 4.
dFloat vertexCloud	-	pointer to and array of point.
dFloat strideInBytes	-	vertex size in bytes, must be at least 12.
const dFloat *offsetMatrix	-	pointer to 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.

Return

Pointer to the box

Remarks

Convex hulls are the solution to collision primitive that can not be easily represented by and 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 for cases where the shape is too difficult 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.

Remarks

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.

Remarks

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.

See also

NewtonReleaseCollision, NewtonCreateConvexHullModifier

Create a collision modifier for any convex collision part.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world. NewtonCollision convexHullCollision.

Return

Pointer to the collision modifier

Remarks

The matrix should be arranged in row-major order (this is the way directX stores matrices). a collision modifier can take any type of transformation matrix, as long as the matrix can be invertible by straight Gaussian elimination process. Typical uses are non-uniform scaling, translation and skewing.

Remarks

Collision modifier can be used by the application to achieve effects like animating collision geometry at run time, however care must taken as animation of a collision primitive could result in unwanted penetrations.

See also

NewtonReleaseCollision, NewtonConvexHullModifierSetMatrix, NewtonConvexHullModifierGetMatrix

Get the transformation matrix of a convex hull modifier collision.

Parameters

const NewtonCollision *convexHullModifier	-	pointer to the body.
dFloat *matrixPtr	-	pointer to an array of 16 floats containing the global matrix of the collision modifier.

Return

Nothing.

Remarks

The matrix should be arranged in row-major order (this is the way directX stores matrices). a collision modifier can take any type of transformation matrix, as long as the matrix can be invertible by straight Gaussian elimination process. Typical uses are non-uniform scaling, translation and skewing.

Remarks

Collision modifier can be used by the application to achieve effects like animating collision geometry at run time, however care must taken as animation of a collision primitive could result into unwanted penetrations.

See also

NewtonCreateConvexHullModifier, NewtonConvexHullModifierSetMatrix

Set the transformation matrix of a convex hull modifier collision.

Parameters

const NewtonCollision *convexHullModifier	-	pointer to the body.
const dFloat *matrixPtr	-	pointer to an array of 16 floats containing the global matrix of the collision modifier.

Return

Nothing.

Remarks

The matrix should be arranged in row-major order (this is the way directX stores matrices). a collision modifier can take any type of transformation matrix, as long as the matrix can be invertible by straight Gaussian elimination process. Typical uses are non-uniform scaling, translation and skewing.

Remarks

Collision modifier can be used by the application to achieve effects like animating collision geometry at run time, however care must taken as animation of a collision primitive could result into unwanted penetrations.

See also

NewtonCreateConvexHullModifier, NewtonConvexHullModifierGetMatrix

Create a container to hold an array of convex collision primitives.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int count	-	number of primitives in the array.
const NewtonCollision **collisionPrimitiveArray	-	pointer to an array of convex collision primitives. This array must be filled with convex collision primitives before this function is called.

Return

Pointer to the compound collision.

Remarks

Compound collision primitives can only be made of convex collision primitives and they can not contain compound collision. Therefore they are treated as convex primitives.

Remarks

Compound collision primitives are treated as instance collision objects that can not shared by multiples rigid bodies.

Remarks

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.

See also

NewtonReleaseCollision

Store a user defined value with a convex collision primitive.

Parameters

const NewtonCollision convexCollision	-	is the pointer to a convex collision primitive.
unsigned id	-	value to store with the collision primitive.

Return

nothing

Remarks

the application can store an id with any collision primitive. This id can be used to identify what type of collision primitive generated a contact.

See also

NewtonMaterialGetBodyCollisionID, NewtonConvexCollisionGetUserID, NewtonCreateBox, NewtonCreateSphere

Return a user define value with a convex collision primitive.

Parameters

const NewtonCollision convexCollision

-

is the pointer to a convex collision primitive.

Return

user id

Remarks

the application can store an id with any collision primitive. This id can be used to identify what type of collision primitive generated a contact.

See also

NewtonMaterialGetBodyCollisionID, NewtonMaterialGetBodyCollisionID, NewtonCreateBox, NewtonCreateSphere

calculate the total volume defined by a convex collision geometry.

Parameters

const NewtonCollision *convexCollision

-

pointer to the collision.

Return

collision geometry volume. This function will return zero if the body collision geometry is no convex.

Remarks

The total volume calculated by the function is only an approximation of the ideal volume. This is not an error, it is a fact resulting from the polygonal representation of convex solids.

Remarks

This function can be used to assist the application in calibrating features like fluid density weigh factor when calibrating buoyancy forces for more realistic result.

See also

NewtonBodyAddBuoyancyForce

Calculate the three principal axis and the the values of the inertia matrix of a convex collision objects.

Parameters

const NewtonCollision convexCollision	-	is the pointer to a convex collision primitive.
dFloat *inertia	-	pointer to and array of a least 3 floats to hold the values of the principal inertia.
dFloat *origin	-	pointer to and array of a least 3 floats to hold the values of the center of mass for the principal inertia.

Remarks

This function calculate a general inertial matrix for arbitrary convex collision including compound collisions.

See also

NewtonBodySetMassMatrix, NewtonBodyGetMassMatrix, NewtonBodySetCentreOfMass, NewtonBodyGetCentreOfMass

Create a complex collision geometry to be controlled by the application.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const dFloat *minBox	-	pointer to an array of at least three floats to hold minimum value for the box relative to the collision.
const dFloat *maxBox	-	pointer to an array of at least three floats to hold maximum value for the box relative to the collision.
void *userData	-	pointer to user data to be used as context for event callback.
NewtonUserMeshCollisionCollideCallback collideCallback	-	pointer to an event function for providing Newton with the polygon inside a given box region.
NewtonUserMeshCollisionRayHitCallback rayHitCallBack	-	pointer to an event function for providing Newton with ray intersection information.
NewtonUserMeshCollisionDestroyCallback destroyCallback	-	pointer to an event function for destroying any data allocated for use by the application.

Return

Pointer to the user collision.

Remarks

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.

Remarks

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.

Remarks

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.

Remarks

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.

See also

NewtonReleaseCollision

Create an empty complex collision geometry tree.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
NewtonTreeCollisionCallback *userCallback	-	pointer to an event function to call before Newton evaluates the polygons colliding with a body. This parameter can be NULL.

Return

Pointer to the collision tree.

Remarks

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.

Remarks

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.

Remarks

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 by the engine, as well as speed up some calculations.

See also

NewtonTreeCollisionBeginBuild, NewtonTreeCollisionAddFace, NewtonTreeCollisionEndBuild, NewtonTreeCollisionSerialize, NewtonCreateTreeCollisionFromSerialization, NewtonTreeCollisionGetFaceAtribute, NewtonTreeCollisionSetFaceAtribute, NewtonReleaseCollision

Prepare a TreeCollision to begin to accept the polygons that comprise the collision mesh.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world.

Return

Nothing.

See also

NewtonTreeCollisionAddFace, NewtonTreeCollisionEndBuild

Add an individual polygon to a TreeCollision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int vertexCount	-	number of vertex in vertexPtr
const dFloat *vertexPtr	-	pointer to an array of vertex. The vertex should consist of at least 3 floats each.
int strideInBytes	-	size of each vertex in bytes. This value should be 12 or larger.
int faceAttribute	-	id that identifies the polygon. The application can use this value to customize the behavior of the collision geometry.

Return

Nothing.

Remarks

After the call to NewtonTreeCollisionBeginBuild the TreeCollision is ready to accept polygons. The application should iterate through the application's mesh, adding the mesh polygons to the TreeCollision one at a time. The polygons must be flat and non-self intersecting.

See also

NewtonTreeCollisionAddFace, NewtonTreeCollisionEndBuild

Finalize the construction of the polygonal mesh.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int optimize	-	flag that indicates to Newton whether it should optimize this mesh. Set to 1 to optimize the mesh, otherwise 0.

Return

Nothing.

Remarks

After the application has finished adding polygons to the TreeCollision, it must call this function 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 function with the parameter optimize set to zero, will leave the mesh geometry unaltered.

See also

NewtonTreeCollisionAddFace, NewtonTreeCollisionEndBuild

Serialize a TreeCollision.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
NewtonSerialize callback	-	pointer to the event function that will do the serialization.
void *serializeHandle	-	user data that will be passed to the NewtonSerialize callback.

Return

Nothing.

Remarks

Small and medium size TreeCollision objects (under 50000 polygons) can be constructed at application startup without significant processing overhead. However, for very large polygons sets (over 50000 polygons) it is recommended that the application use NewtonCreateTreeCollision in an off-line tool. Then the application can call this function to store the TreeCollision to a file or any file packer system the application is using. At run time the application can use the function NewtonCreateTreeCollisionFromSerialization to create and load a pre-made TreeCollision

See also

NewtonCreateTreeCollisionFromSerialization

Create a tree collision and load the polygon mesh via a serialization function.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
NewtonTreeCollisionCallback *userCallback	-	pointer to an event function to call before Newton is begins collecting polygons that are colliding with a body. This parameter can be NULL.
NewtonSerialize callback	-	pointer to the callback function that will handle the serialization.
void *userData	-	user data that will be passed as the argument to NewtonSerialize callback.

Return

Nothing.

Remarks

Small and medium size TreeCollision objects (under 50000 polygons) can be constructed at application startup without significant processing overhead. However, for very large polygons sets (over 50000 polygons) it is recommended that the application use NewtonCreateTreeCollision in an off-line tool. Then the application can call this function to store the TreeCollision to a file or any file packer system the application is using. At run time the application can use the function NewtonCreateTreeCollisionFromSerialization to create and load a pre-made TreeCollision

See also

NewtonTreeCollisionSerialize, NewtonReleaseCollision

Get the user defined collision attributes stored with each face of the collision mesh.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const int *faceIndexArray	-	pointer to the face index list passed to the function NewtonTreeCollisionCallback userCallback

Return

User id of the face.

Remarks

This function is used to obtain the user data stored in faces of the collision geometry. The application can use this user data to achieve per polygon material behavior in large static collision meshes.

See also

NewtonTreeCollisionSetFaceAtribute, NewtonCreateTreeCollision, NewtonCreateTreeCollisionFromSerialization

Change the user defined collision attribute stored with faces of the collision mesh.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const int *faceIndexArray	-	pointer to the face index list passed to the function NewtonTreeCollisionCallback userCallback
int attribute	-	value of the user defined attribute to be stored with the face.

Return

User id of the face.

Remarks

This function is used to obtain the user data stored in faces of the collision geometry. The application can use this user data to achieve per polygon material behavior in large static collision meshes. By changing the value of this user data the application can achieve modifiable surface behavior with the collision geometry. For example, in a driving game, the surface of a polygon that represents the street can changed from pavement to oily or wet after some collision event occurs.

See also

NewtonTreeCollisionGetFaceAtribute, NewtonCreateTreeCollision, NewtonCreateTreeCollisionFromSerialization

Calculate the closest point between a point and convex collision primitive.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
dFloat *point	-	pointer to and array of a least 3 floats representing the origin.
const NewtonCollision *collision	-	pointer to collision primitive.
const dFloat *matrix	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveA.
dFloat *contact	-	pointer to and array of a least 3 floats to contain the closest point to collisioA.
dFloat *normal	-	pointer to and array of a least 3 floats to contain the separating vector normal.

Return

one if the two bodies are disjoint and the closest point could be found, zero if the point is inside the convex primitive.

Remarks

This function can be used as a low-level building block for a stand-alone collision system. Applications that have already there own physics system, and only want and quick and fast collision solution, can use Newton advanced collision engine as the low level collision detection part. To do this the application only needs to initialize Newton, create the collision primitives at application discretion, and just call this function when the objects are in close proximity. Applications using Newton as a collision system only, are responsible for implementing their own broad phase collision determination, based on any high level tree structure. Also the application should implement their own trivial aabb test, before calling this function .

Remarks

the current implementation of this function do work on collision trees, or user define collision.

See also

NewtonCollisionCollideContinue, NewtonCollisionClosestPoint, NewtonCollisionCollide, NewtonCollisionRayCast, NewtonCollisionCalculateAABB

Calculate the closest points between two disjoint convex collision primitive.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *collisionA	-	pointer to collision primitive A.
const dFloat *matrixA	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveA.
const NewtonCollision *collisionB	-	pointer to collision primitive B.
const dFloat *matrixB	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveB.
dFloat *contactA	-	pointer to and array of a least 3 floats to contain the closest point to collisionA.
dFloat *contactB	-	pointer to and array of a least 3 floats to contain the closest point to collisionB.
dFloat *normalAB	-	pointer to and array of a least 3 floats to contain the separating vector normal.

Return

one if the tow bodies are disjoint and he closest point could be found, zero if the two collision primitives are intersecting.

Remarks

This function can be used as a low-level building block for a stand-alone collision system. Applications that have already there own physics system, and only want and quick and fast collision solution, can use Newton advanced collision engine as the low level collision detection part. To do this the application only needs to initialize Newton, create the collision primitives at application discretion, and just call this function when the objects are in close proximity. Applications using Newton as a collision system only, are responsible for implementing their own broad phase collision determination, based on any high level tree structure. Also the application should implement their own trivial aabb test, before calling this function .

Remarks

the current implementation of this function does not work on collision trees, or user define collision.

See also

NewtonCollisionCollideContinue, NewtonCollisionPointDistance, NewtonCollisionCollide, NewtonCollisionRayCast, NewtonCollisionCalculateAABB

Calculate contact points between two collision primitive.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int maxSize	-	size of maximum number of elements in contacts, normals, and penetration.
const NewtonCollision *collisionA	-	pointer to collision primitive A.
const dFloat *matrixA	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveA.
const NewtonCollision *collisionB	-	pointer to collision primitive B.
const dFloat *matrixB	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveB.
dFloat *contacts	-	pointer to and array of a least 3 times maxSize floats to contain the collision contact points.
dFloat *normals	-	pointer to and array of a least 3 times maxSize floats to contain the collision contact normals.
dFloat *penetration	-	pointer to and array of a least maxSize floats to contain the collision penetration at each contact.

Return

the number of contact points.

Remarks

This function can be used as a low-level building block for a stand-alone collision system. Applications that have already there own physics system, and only want and quick and fast collision solution, can use Newton advanced collision engine as the low level collision detection part. To do this the application only needs to initialize Newton, create the collision primitives at application discretion, and just call this function when the objects are in close proximity. Applications using Newton as a collision system only, are responsible for implementing their own broad phase collision determination, based on any high level tree structure. Also the application should implement their own trivial aabb test, before calling this function .

See also

NewtonCollisionCollideContinue, NewtonCollisionClosestPoint, NewtonCollisionPointDistance, NewtonCollisionRayCast, NewtonCollisionCalculateAABB

Calculate time of impact of impact and contact points between two collision primitive.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
int maxSize	-	size of maximum number of elements in contacts, normals, and penetration.
const dFloat timestep	-	maximum time interval consided for the continue collision claculation.
const NewtonCollision *collisionA	-	pointer to collision primitive A.
const dFloat *matrixA	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveA.
const dFloat *velocA	-	pointer to and array of a least 3 times maxSize floats containing the linear velocity of collision primitiveA.
const dFloat *omegaA	-	pointer to and array of a least 3 times maxSize floats containing the angular velocity of collision primitiveA.
const NewtonCollision *collisionB	-	pointer to collision primitive B.
const dFloat *matrixB	-	pointer to an array of 16 floats containing the offset matrix of collision primitiveB.
const dFloat *velocB	-	pointer to and array of a least 3 times maxSize floats containing the linear velocity of collision primitiveB.
const dFloat *omegaB	-	pointer to and array of a least 3 times maxSize floats containing the angular velocity of collision primitiveB.
dFloat *timeOfImpact	-	pointer to least 1 float variable to contain the time of the intersection.
dFloat *contacts	-	pointer to and array of a least 3 times maxSize floats to contain the collision contact points.
dFloat *normals	-	pointer to and array of a least 3 times maxSize floats to contain the collision contact normals.
dFloat *penetration	-	pointer to and array of a least maxSize floats to contain the collision penetration at each contact.

Return

the number of contact points.

Remarks

by passing zero as maxSize not contact will be calculated and the function will just determine the time of impact is any.

Remarks

if the body are interpenetrating the time of impact will be zero.

Remarks

if the bodies do not collide time of impact will be set to timestep

Remarks

This function can be used as a low-level building block for a stand-alone collision system. Applications that have already there own physics system, and only want and quick and fast collision solution, can use Newton advanced collision engine as the low level collision detection part. To do this the application only needs to initialize Newton, create the collision primitives at application discretion, and just call this function when the objects are in close proximity. Applications using Newton as a collision system only, are responsible for implementing their own broad phase collision determination, based on any high level tree structure. Also the application should implement their own trivial aabb test, before calling this function .

See also

NewtonCollisionCollide, NewtonCollisionClosestPoint, NewtonCollisionPointDistance, NewtonCollisionRayCast, NewtonCollisionCalculateAABB

Ray cast specific collision object.

Parameters

const NewtonCollision *collisionPtr	-	pointer to the collision object.
dFloat *p0	-	pointer to an array of at least three floats representing the ray origin in the local space of the geometry.
dFloat *p1	-	pointer to an array of at least three floats representing the ray end in the local space of the geometry.
dFloat *normal	-	pointer to an array of at least three floats to hold the normal at the intersection point.
int *attribute	-	pointer to an array of at least one floats to hold the ID of the face hit by the ray.

Return

the parametric value of the intersection, between 0.0 and 1.0, an value larger than 1.0 if the ray miss.

Remarks

This function is intended for applications using newton collision system separate from the dynamics system, also for applications implementing any king of special purpose logic like sensing distance to another object.

Remarks

the ray most be local to the collisions geometry, for example and application ray casting the collision geometry of of a rigid body, must first take the points p0, and p1 to the local space of the rigid body by multiplying the points by the inverse of he rigid body transformation matrix.

See also

NewtonCollisionClosestPoint, NewtonCollisionPointDistance, NewtonCollisionCollide, NewtonCollisionCalculateAABB

Calculate an axis-aligned bounding box for this collision, the box is calculated relative to offsetMatrix.

Parameters

const NewtonCollision *collisionPtr	-	pointer to the collision object.
const dFloat *offsetMatrix	-	pointer to an array of 16 floats containing the offset matrix used as the coordinate system and center of the AABB.
dFloat *p0	-	pointer to an array of at least three floats to hold minimum value for the AABB.
dFloat *p1	-	pointer to an array of at least three floats to hold maximum value for the AABB.

Return

Nothing.

See also

NewtonCollisionClosestPoint, NewtonCollisionPointDistance, NewtonCollisionCollide, NewtonCollisionRayCast

Convert a collision primitive to a unique instance by removing it for the collision cache.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *collisionPtr	-	pointer to the collision object

Return

Nothing.

Remarks

This function will not make preexisting collision object unique instances, so for best result this function should be call immediately after the creation of the collision object.

Remarks

Collision objects 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.

Release a reference from this collision object returning control to Newton.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *collisionPtr	-	pointer to the collision object

Return

Nothing.

Remarks

Collision objects 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.

Get the three Euler angles from a 4x4 rotation matrix arranged in row-major order.

Parameters

const dFloat matrix	-	pointer to the 4x4 rotation matrix.
dFloat angles	-	pointer to an array of at least three floats to hold the Euler angles.

Return

Nothing.

Remarks

The motivation for this function is that many graphics engines still use Euler angles to represent the orientation of graphics entities. The angles are expressed in radians and represent:

angle[0]	-	rotation about first matrix row
angle[1]	-	rotation about second matrix row
angle[2]	-	rotation about third matrix row

See also

NewtonSetEulerAngle

Build a rotation matrix from the Euler angles in radians.

Parameters

dFloat matrix	-	pointer to the 4x4 rotation matrix.
const dFloat angles	-	pointer to an array of at least three floats to hold the Euler angles.

Return

Nothing.

Remarks

The motivation for this function is that many graphics engines still use Euler angles to represent the orientation of graphics entities. The angles are expressed in radians and represent:

angle[0]	-	rotation about first matrix row
angle[1]	-	rotation about second matrix row
angle[2]	-	rotation about third matrix row

See also

NewtonGetEulerAngle

Create a rigid body.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *collisionPtr	-	pointer to the collision object.

Return

Pointer to the rigid body.

Remarks

This function creates a Newton rigid body and assigns a collisionPtr as the collision geometry representing the rigid body. This function increments the reference count of the collision geometry. All event functions are set to NULL and the material gruopID of the body is set to the default GroupID.

See also

NewtonDestroyBody

Destroy a rigid body.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonBody *bodyPtr	-	pointer to the body to be destroyed.

Return

Nothing.

Remarks

If this function is called from inside a simulation step the destruction of the body will be delayed until end of the time step. This function will decrease the reference count of the collision geometry by one. If the reference count reaches zero, then the collision geometry will be destroyed. This function will destroy all joints associated with this body.

See also

NewtonCreateBody

Store a user defined data value with the body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
void *userDataPtr	-	pointer to the user defined user data value.

Return

Nothing.

Remarks

The application can store a user defined value with the Body. This value can be the pointer to a structure containing some application data for special effect. if the application allocate some resource to store the user data, the application can register a joint destructor to get rid of the allocated resource when the body is destroyed

See also

NewtonBodyGetUserData, NewtonBodySetDestructorCallback

Retrieve a user defined data value stored with the body.

Parameters

const NewtonBody *bodyPtr

-

pointer to the body.

Return

The user defined data.

Remarks

The application can store a user defined value with a rigid body. This value can be the pointer to a structure which is the graphical representation of the rigid body.

See also

NewtonBodySetUserData

Retrieve get the pointer to the world from the body.

Parameters

const NewtonBody *bodyPtr

-

pointer to the body.

Return

the world that own this body.

Remarks

The application can use this function to determine what world own this body. If the application have to get the world from a joint, it can do so by getting one of the bodies attached to the joint and getting the world from that body.

Assign a transformation event function to the body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
NewtonSetTransform callback	-	pointer to a function callback in used to update the transformation matrix of the visual object that represents the rigid body.

Return

Nothing.

Remarks

The function NewtonSetTransform callback is called by the Newton engine every time a visual object that represents the rigid body has changed. The application can obtain the pointer user data value that points to the visual object. The Newton engine does not call the NewtonSetTransform callback function for bodies that are inactive or have reached a state of stable equilibrium.

Remarks

The matrix should be organized in row-major order (this is the way directX stores matrices). If you are using OpenGL matrices (column-major) you will need to transpose the matrices into a local array, before you pass them to Newton.

See also

NewtonBodyGetUserData, NewtonBodyGetUserData

Assign an activation/deativation callback function.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
NewtonBodyActivationStatem callback	-	pointer to a function callback is used to be called when the body is about to be activated or deactivated.

Return

Nothing.

Remarks

this function sets an activation and deactivation callback with the body. The application can use this method to implement advanced scene management control.

Assign an event function for applying external force and torque to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
NewtonApplyForceAndTorque callback	-	pointer to a function callback used to apply force and torque to a rigid body.

Return

Nothing.

Remarks

Before the NewtonApplyForceAndTorque callback is called for a body, Newton first clears the net force and net torque for the body.

Remarks

The function NewtonApplyForceAndTorque callback is called by the Newton Engine every time an active body is going to be simulated. The Newton Engine does not call the NewtonApplyForceAndTorque callback function for bodies that are inactive or have reached a state of stable equilibrium.

See also

NewtonBodyGetUserData, NewtonBodyGetUserData, NewtonBodyGetForceAndTorqueCallback

Return the pointer to the current force and torque call back function.

Parameters

const NewtonBody *bodyPtr

-

pointer to the body.

Return

pointer to the force call back.

Remarks

This function can be used to concatenate different force calculation components making more modular the design of function components dedicated to apply special effect. For example a body may have a basic force a force that only apply the effect of gravity, but that application can place a region in where there can be a fluid volume, or another gravity field. we this function the application can read the correct function and save into a local variable, and set a new one. this new function will firs call the save function pointer and upon return apply the correct effect. this similar to the concept of virtual methods on objected oriented languages.

Remarks

The function NewtonApplyForceAndTorque callback is called by the Newton Engine every time an active body is going to be simulated. The Newton Engine does not call the NewtonApplyForceAndTorque callback function for bodies that are inactive or have reached a state of stable equilibrium.

See also

NewtonBodyGetUserData, NewtonBodyGetUserData, NewtonBodySetForceAndTorqueCallback

Assign an event function to be called when this body is about to be destroyed.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body to be destroyed.
NewtonBodyDestructor callback	-	pointer to a function callback.

Return

Nothing.

Remarks

This function NewtonBodyDestructor callback acts like a destruction function in CPP. This function is called when the body and all data joints associated with the body are about to be destroyed. The application could use this function to destroy or release any resource associated with this body. The application should not make reference to this body after this function returns.

Remarks

The destruction of a body will destroy all joints associated with the body.

See also

NewtonBodyGetUserData, NewtonBodyGetUserData

Set the mass matrix of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
dFloat mass	-	mass value.
dFloat Ixx	-	moment of inertia of the first principal axis of inertia of the body.
dFloat Iyy	-	moment of inertia of the first principal axis of inertia of the body.
dFloat Izz	-	moment of inertia of the first principal axis of inertia of the body.

Return

Nothing.

Remarks

Newton algorithms have no restriction on the values for the mass, but due to floating point dynamic range (24 bit precision) it is best if the ratio between the heaviest and the lightest body in the scene is limited to 200. There are no special utility functions in Newton to calculate the moment of inertia of common primitives. The application should specify the inertial values, keeping in mind that realistic inertia values are necessary for realistic physics behavior.

See also

NewtonConvexCollisionCalculateInertialMatrix, NewtonBodyGetMassMatrix, NewtonBodyGetInvMass

Get the mass matrix of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
dFloat *mass	-	pointer to a variable that will hold the mass value of the body.
dFloat *Ixx	-	pointer to a variable that will hold the moment of inertia of the first principal axis of inertia of the body.
dFloat *Iyy	-	pointer to a variable that will hold the moment of inertia of the first principal axis of inertia of the body.
dFloat *Izz	-	pointer to a variable that will hold the moment of inertia of the first principal axis of inertia of the body.

Return

Nothing.

See also

NewtonBodySetMassMatrix, NewtonBodyGetInvMass

Get the inverse mass matrix of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
dFloat *invMass	-	pointer to a variable that will hold the mass inverse value of the body.
dFloat *invIxx	-	pointer to a variable that will hold the moment of inertia inverse of the first principal axis of inertia of the body.
dFloat *invIyy	-	pointer to a variable that will hold the moment of inertia inverse of the first principal axis of inertia of the body.
dFloat *invIzz	-	pointer to a variable that will hold the moment of inertia inverse of the first principal axis of inertia of the body.

Return

Nothing.

See also

NewtonBodySetMassMatrix, NewtonBodyGetMassMatrix

Set the transformation matrix of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *matrixPtr	-	pointer to an array of 16 floats containing the global matrix of the rigid body.

Return

Nothing.

Remarks

The matrix should be arranged in row-major order (this is the way directX stores matrices). If you are using OpenGL matrices (column-major) you will need to transpose you matrices into a local array, before passing them to Newton.

See also

NewtonBodyGetMatrix, NewtonBodySetMatrixRecursive

Apply hierarchical transformation to a body.

Parameters

const NewtonWorld *newtonWorld	-	pointer to the Newton world.
const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *matrixPtr	-	pointer to an array of 16 floats containing the global matrix of the rigid body.

Return

Nothing.

Remarks

This function applies the transformation matrix to the body and also applies the appropriate transformation matrix to set of articulated bodies. If the body is in contact with another body the other body is not transformed.

Remarks

this funtion should not be used to transform set of articulated bodies that are connected to a static body. doing so will result in umprediactable results. Think for example moving a chain attached to a ceiling from one place to another, to do that in real life a person first need to desconect the chain (destroy the joint), move the chain (apply teh tranfomation to the entire chain), the reconect it in the new position (recreate the joint again).

Remarks

this function will set to zero the linear and angular velocity of all bodies that are part of the set of articulated body array.

Remarks

The matrix should be arranged in row-major order (this is the way directX stores matrices). If you are using OpenGL matrices (column-major) you will need to transpose you matrices into a local array, before passing them to Newton.

See also

NewtonBodySetMatrix

Get the transformation matrix of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *matrixPtr	-	pointer to an array of 16 floats that will hold the global matrix of the rigid body.

Return

Nothing.

Remarks

The matrix should be arranged in row-major order (this is the way directX stores matrices). If you are using OpenGL matrices (column-major) you will need to transpose you matrices into a local array, before passing them to Newton.

See also

NewtonBodySetMatrix

Set the net force applied to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *forcePtr	-	pointer to an array of 3 floats containing the net force to be applied to the body.

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

See also

NewtonBodyAddForce, NewtonBodyGetForce

Add the net force applied to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body to be destroyed.
const dFloat *forcePtr	-	pointer to an array of 3 floats containing the net force to be applied to the body.

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

See also

NewtonBodySetForce, NewtonBodyGetForce

Get the net force applied to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *forcePtr	-	pointer to an array of 3 floats to hold the net force of the body.

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

See also

NewtonBodyAddForce, NewtonBodyGetForce

Set the net torque applied to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *torquePtr	-	pointer to an array of 3 floats containing the net torque to be applied to the body.

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

See also

NewtonBodyAddTorque, NewtonBodyGetTorque

Set the relative position of the center of mass of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *comPtr	-	pointer to an array of 3 floats containing the relative offset of the centre of mass of the body.

Return

Nothing.

Remarks

This funtion can be used to set the relative offset of the centre of mass of a rigid body. when a rigid body is created the centre of mass is set the the point c(0, 0, 0), and normally this is the best setting for a rigid body. However the are situations in which and object does not have simetry or simple some kind of special effect is desired, and this origin need to be changed.

Remarks

Care must be taken when ofsseting the centre of mass of a body. The applycation must make sure that the external torques resulting from forces applied at at point relative to the center of mass are calculared apropriatly. this could be done Transform and Torque callback funtion as teh follow psudo code fragment shows:

Matrix matrix; Vector centre;

NewtonGatMetrix(body, matrix) NewtonGetCentreOfMass(body, centre);

for global space torque. Vector localForce (fx, fy, fz); Vector localPosition (x, y, z);

Vector localTroque (crossproduct ((localPosition

-

centre). localForce); Vector globalTroque (matrix.RotateVector (localTroque));

for global space torque. Vector globalCentre (matrix.TranformVector (centre)); Vector globalPosition (x, y, z); Vector globalForce (fx, fy, fz);

Vector globalTroque (crossproduct ((globalPosition

-

globalCentre). globalForce);

See also

NewtonConvexCollisionCalculateInertialMatrix, NewtonBodyGetCentreOfMass

Add the net torque applied to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *torquePtr	-	pointer to an array of 3 floats containing the net torque to be applied to the body.

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

See also

NewtonBodySetTorque, NewtonBodyGetTorque

Get the net torque applied to a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const dFloat *torquePtr	-	pointer to an array of 3 floats to hold the net torque of the body.

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

See also

NewtonBodyAddTorque, NewtonBodyGetTorque

Get the relative position of the center of mass of a rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
dFloat *comPtr	-	pointer to an array of 3 floats to hold the relative offset of the centre of mass of the body.

Return

Nothing.

Remarks

This function can be used to set the relative offset of the center of mass of a rigid body. when a rigid body is crated 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 the are situations in which and object does not have simetry or simple some kind of special effect is desired, and this origin need to be changed.

Remarks

This function can be used in conjunction with NewtonConvexCollisionCalculateInertialMatrix

See also

NewtonConvexCollisionCalculateInertialMatrix, NewtonBodySetCentreOfMass

Add buoyancy force and torque for bodies immersed in a fluid.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
dFloat fluidDensity	-	fluid density.
dFloat fluidLinearViscosity	-	fluid linear viscosity (resistance to linear tranlation).
dFloat fluidAngularViscosity	-	fluid angular viscosity (resistance to rotation).
const dFloat *gravityVector	-	pointer to an array of floats containing the gravity vector.
NewtonGetBuoyancyPlane *buoyancyPlane	-	pointer to an array of at least 4 floats containing the plane equation of the surface of the fluid. This parameter can be NULL

Return

Nothing.

Remarks

This function is only effective when called from NewtonApplyForceAndTorque callback

Remarks

This function adds buoyancy force and torque to a body when it is immersed in a fluid. The force is calculated according to Archimedes’ Buoyancy Principle. When the parameter buoyancyPlane is set to NULL, the body is considered to completely immersed in the fluid. This can be used to simulate boats and lighter than air vehicles etc..

Remarks

If buoyancyPlane return 0 buoyancy calculation for this collision primitive is inghnored, this coudl be used to filter bouyancy calculation of compound collision geometry with diffrents IDs.

See also

NewtonConvexCollisionCalculateVolume

Assign a collision primitive to the body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
const collisionPtr *collisionPtr	-	pointer to the new collision geometry.

Return

Nothing.

Remarks

This function replaces a collision geometry of a body with the new collision geometry. This function increments the reference count of the collision geometry and decrements the reference count of the old collision geometry. If the reference count of the old collision geometry reaches zero, the old collision geometry is destroyed. This function can be used to swap the collision geometry of bodies at runtime.

See also

NewtonCreateBody, NewtonBodyGetCollision

Enable or disable Coriolis and gyroscopic force calculation for this body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
int mode	-	force mode zero indicate not gyroscopic force calculation.

Return

Nothing.

Remarks

Gyroscopic forces internal forces generated as a result of an asymmetric tensor. They are a pure mathematical consequence that the physics have to comply in order to agree with the math. As Gyroscopic forces are not real forces but the result of net unbalance of the changing inertia tensor or a rigid body when its angular velocity is measured on a reference frame different than the body’s own. Gyroscopic forces are extremely non linear by nature, therefore a first order implicit integrator will have a extremely hard time at dealing with this kind of forces, however because the fact that they are not real forces they do not make much difference in the outcome of the integration. Fortunately due to the fact that the magnitude of gyroscopic forces is proportional to the unbalance of the inertia tensor, it is possible to disregard the effect of this forces by assuming their inertial tensor is symmetric for the purpose of this calculation. For most cases an ordinary person is not capable to distinguish the motion of a body subject to gyroscopic forces and one that is not, especially when the motion is constrained. Because of this fact gyroscopic force are turned off by default in Newton, however there are cases when the desire effect is precisely to simulate these forces like a spinning top, or the design of a space navigational system, etc. The most important feature of gyroscopic forces is that they make the rigid body to process.

Get the collision primitive of a body.

Parameters

const NewtonBody *bodyPtr

-

pointer to the body.

Return

Pointer to body collision geometry.

Remarks

This function does not increment the reference count of the collision geometry.

See also

NewtonCreateBody, NewtonBodySetCollision

Assign a material group id to the body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
int id	-	id of a previously created material group.

Return

Nothing.

Remarks

When the application creates a body, the default material group, defaultGroupId, is applied by default.

See also

NewtonBodyGetMaterialGroupID, NewtonMaterialCreateGroupID, NewtonMaterialGetDefaultGroupID

Get the material group id of the body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
int id	-	id of a previously created material group.

Return

Nothing.

See also

NewtonBodySetMaterialGroupID

Set the continuous collision state mode for this rigid body.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
int state	-	collision state. 1 indicates this body may tunnel through other objects while moving at high speed. 0 ignore high speed collision checks.

Return

Nothing.

Remarks

continue collision mode enable allow the engine to predict colliding contact on rigid bodies Moving at high speed of subject to strong forces.

Remarks

continue collision mode does not prevent rigid bodies from interpenetration instead it prevent bodies from passing trough each others by extrapolating contact points when the bodies normal contact calculation determine the bodies are not colliding.

Remarks

for performance reason the bodies angular velocities is only use on the broad face of the collision, but not on the contact calculation.

Remarks

continue collision does not perform back tracking to determine time of contact, instead it extrapolate contact by incrementally extruding the collision geometries of the two colliding bodies along the linear velocity of the bodies during the time step, if during the extrusion colliding contact are found, a collision is declared and the normal contact resolution is called.

Remarks

for continue collision to be active the continue collision mode must on the material pair of the colliding bodies as well as on at least one of the two colliding bodies.

Remarks

Because there is penalty of about 40% to 80% depending of the shape complexity of the collision geometry, this feature is set off by default. It is the job of the application to determine what bodies need this feature on. Good guidelines are: very small objects, and bodies that move a height speed.

See also

NewtonBodyGetContinuousCollisionMode, NewtonBodySetContinuousCollisionMode

Get the continuous collision state mode for this rigid body.

Parameters

const NewtonBody *bodyPtr

-

pointer to the body.

Return

Nothing.

Remarks

Remark: Because there is there is penalty of about 3 to 5 depending of the shape complexity of the collision geometry, this feature is set off by default. It is the job of the application to determine what bodies need this feature on. Good guidelines are: very small objects, and bodies that move a height speed.

Remark

this feature is currently disabled:

See also

NewtonBodySetContinuousCollisionMode, NewtonBodySetContinuousCollisionMode

Set the collision state flag of this body when the body is connected to another body by a hierarchy of joints.

Parameters

const NewtonBody *bodyPtr	-	pointer to the body.
int state	-	collision state. 1 indicates this body will collide with any linked body. 0 disable collision with body connected to this one by joints.

Return

Nothing.

Remarks

sometimes when making complicated arrangements of linked bodies it is possible the collision geometry of these bodies is in the way of the joints work space. This could be a problem for the normal operation of the joints. When this situation happens the application can determine which bodies are the problem and disable collision for those bodies while they are linked by joints. For the collision to be disable for a pair of body, both bodies must have the collision disabled. If the joints connecting the bodies are destroyed these bodies become collidable automatically. This feature can also be achieved by making special material for the whole configuration of jointed bodies, however it is a lot easier just to set collision disable for jointed bodies.

See also

NewtonBodySetMaterialGroupID

Get the collision state flag when the body is joint.

Parameters

const NewtonBody *bodyPtr

-

pointer to the body.

Return

return the collision state flag for this body.

See also

NewtonBodySetMaterialGroupID

Set the auto-activation mode for this body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
int state	-	active mode: 1 = auto-activation on (controlled by Newton). 0 = auto-activation off (controlled by the application).

Return

Nothing.

Remarks

Bodies are created with auto-activation on by default.

Remarks

Autoactivation enabled is the default state for the majority of bodies in a large scene. However, for player control, ai control or some other special circumstance, the application may want to control the activation/deactivation of the body. In that case, the application may call NewtonBodySetAutoFreeze (body, 0) followed by NewtonWorldUnfreezeBody(world, body), this will make the body active forever.

See also

NewtonWorldFreezeBody, NewtonWorldUnfreezeBody, NewtonBodyGetAutoFreeze, NewtonBodySetFreezeTreshold

Get the auto-activation state of the body.

Parameters

const NewtonBody *bodyPtr

-

is the pointer to the body.

Return

Freeze state: 1 = frozen. 0 = active.

See also

NewtonBodySetAutoFreeze, NewtonBodyGetSleepingState

Return the sleep mode of a rigid body.

Parameters

const NewtonBody *bodyPtr

-

is the pointer to the body.

Return

Autoactivation state: 1 = auto-activation on. 0 = auto-activation off.

See also

NewtonBodySetAutoFreeze

Set the minimum values for velocity of a body that will be considered at rest.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
dFloat freezeSpeedMag2	-	magnitude squared of the velocity threshold.
dFloat freezeOmegaMag2	-	magnitude squared of angular velocity threshold.
int framesCount	-	number of frames the body velocity and angular will not excide freezeSpeedMag and freezeOmegaMag.

Remarks

Ideally, a body should be deactivated when it reaches a state of stable equilibrium. However, because of floating point inaccuracy, discrete time step simulation and other factors it is virtually impossible for a body to reach that state in a real-time simulation. Therefore, in the Newton World, a body is considered to be in stable equilibrium when its velocity and angular velocity fall below some threshold for a consecutive number of frames.

Remarks

The default and minimum values for the thresholds is 0.01 for speed and 10 for frames count. These values are tuned for single objects colliding under the influence of gravity. It is possible that for complex configuration of bodies like multiples pendulums, rag dolls, etc. these values may need to be increased. This is because joints have the property that they add a small amount of energy to the system in order to reduce the separation error. This may cause the bodies reach a state of unstable equilibrium. That is, when a body oscillates between two different positions because the energy added to the body is equal to the energy dissipated by the integrator. This is a situation that is hard to predict, and the best solution is to tweak these values for specific cases.

See also

NewtonBodySetAutoFreeze, NewtonBodyGetFreezeTreshold

Get the minimum values for velocity of a body the will be considered at rest.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
dFloat freezeSpeedMag2	-	point the to a dFloat to hold the velocity threshold
dFloat freezeOmegaMag2	-	point the to a dFloat to hold the angular velocity threshold

See also

NewtonBodySetFreezeTreshold

Get the world axis aligned bounding box (AABB) of the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
dFloat *p0	-	pointer to an array of at least three floats to hold minimum value for the AABB.
dFloat *p1	-	pointer to an array of at least three floats to hold maximum value for the AABB.

Set the global linear velocity of the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
const dFloat *velocity	-	pointer to an array of at least three floats containing the velocity vector.

See also

NewtonBodyGetVelocity

Get the global linear velocity of the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
const dFloat *velocity	-	pointer to an array of at least three floats to hold the velocity vector.

See also

NewtonBodySetVelocity

Set the global angular velocity of the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
const dFloat *omega	-	pointer to an array of at least three floats containing the angular velocity vector.

See also

NewtonBodyGetOmega

Get the global angular velocity of the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body
dFloat *omega	-	pointer to an array of at least three floats to hold the angular velocity vector.

See also

NewtonBodySetOmega

Apply the linear viscous damping coefficient to the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
dFloat linearDamp	-	linear damping coefficient.

Remarks

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.

Remarks

The dampening viscous friction force is added to the external force applied to the body every frame before going to the solver-integrator. This force is proportional to the square of the magnitude of the velocity to the body in the opposite direction of the velocity of the body. An application can set linearDamp to zero when the application takes 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 is set to a non-zero value for the majority of background bodies. This saves the application from having to control these forces and also prevents the integrator from adding very large velocities to a body.

See also

NewtonBodyGetLinearDamping

Get the linear viscous damping of the body.

Parameters

const NewtonBody *bodyPtr

-

is the pointer to the body.

Return

The linear damping coefficient.

See also

NewtonBodySetLinearDamping

Apply the angular viscous damping coefficient to the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
dFloat *angularDamp	-	pointer to an array of at least three floats containing the angular damping coefficients for the principal axis of the body.

Remarks

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.

Remarks

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 recomended 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.

See also

NewtonBodyGetAngularDamping

Get the linear viscous damping of the body.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
dFloat *angularDamp	-	pointer to an array of at least three floats to hold the angular damping coefficient for the principal axis of the body.

See also

NewtonBodySetAngularDamping

Iterate thought polygon of the collision geometry of a body calling the function callback.

Parameters

const NewtonBody *bodyPtr	-	is the pointer to the body.
NewtonCollisionIterator callback	-	application define callback

Return

nothing

Remarks

This function can be called by the application in order to show the collision geometry. The application should provide a pointer to the function NewtonCollisionIterator, Newton will convert the collision geometry into a polygonal mesh, and will call callback for every polygon of the mesh

Remarks

this function affect severely the performance of Newton. The application should call this function only for debugging purpose

Remarks

This function will ignore user define collision mesh See also: NewtonWorldForEachBodyDo

Add an impulse to a specific point on a body.

Parameters

const NewtonWorld *newtonWorld	-	pointer to the Newton world.
const NewtonBody *bodyPtr	-	is the pointer to the body.
const dFloat pointDeltaVeloc	-	pointer to an array of at least three floats containing the desired change in velocity to point pointPosit.
const dFloat pointPosit	-	pointer to an array of at least three floats containing the center of the impulse in global space.

Return

Nothing.

Remarks

This function will activate the body.

Remarks

pointPosit and pointDeltaVeloc must be specified in global space.

Remarks

pointDeltaVeloc represent a change in velocity. For example, a value of pointDeltaVeloc of (1, 0, 0) changes the velocity of bodyPtr in such a way that the velocity of point pointDeltaVeloc will increase by (1, 0, 0)

Remarks

Because pointDeltaVeloc represents a change in velocity, this function must be used with care. Repeated calls to this function will result in an increase of the velocity of the body and may cause to integrator to lose stability.

Create a ball an socket joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *pivotPoint	-	is origin of ball and socket in global space.
const NewtonBody *childBody	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.
const NewtonBody *parentBody	-	is the pointer to the parent rigid body, this body can be NULL or any kind of rigid body.

Return

Pointer to the ball and socket joint.

Remarks

This function creates a ball and socket and add it to the world. By default joint disables collision with the linked bodies.

Set the ball and socket cone and twist limits.

Parameters

const NewtonJoint *ball	-	is the pointer to a ball and socket joint.
const NewtonCollision *pin	-	pointer to a unit vector defining the cone axis in global space.
const dFloat maxConeAngle	-	max angle in radians the attached body is allow to swing relative to the pin axis, a value of zero will disable this limits.
const dFloat maxTwistAngle	-	max angle in radians the attached body is allow to twist relative to the pin axis, a value of zero will disable this limits.

Remarks

limits are disabled at creation time. A value of zero for maxConeAngle disable the cone limit, a value of zero for maxTwistAngle disable the twist limit all non-zero value for maxConeAngle are clamped between 5 degree and 175 degres

See also

NewtonConstraintCreateBall

Set an update call back to be called when either of the two bodies linked by the joint is active.

Parameters

const NewtonJoint *ball	-	pointer to the joint.
NewtonBallCallBack callback	-	pointer to the joint function call back.

Return

nothing.

Remarks

if the application wants to have some feedback from the joint simulation, the application can register a function update callback to be called every time any of the bodies linked by this joint is active. This is useful to provide special effects like particles, sound or even to simulate breakable moving parts.

See also

NewtonJointSetUserData

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *ball	-	pointer to the joint.
dFloat *angle	-	pointer to an array of a least three floats to hold the joint relative Euler angles.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonBallSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *ball	-	pointer to the joint.
dFloat *omega	-	pointer to an array of a least three floats to hold the joint relative angular velocity.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonBallSetUserCallback

Get the total force asserted over the joint pivot point, to maintain the constraint.

Parameters

const NewtonJoint *ball	-	pointer to the joint.
dFloat *force	-	pointer to an array of a least three floats to hold the force value of the joint.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can destroy the joint if the force exceeds some predefined value.

See also

NewtonBallSetUserCallback

Create a hinge joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *pivotPoint	-	is origin of the hinge in global space.
const NewtonCollision *pinDir	-	is the line of action of the hinge in global space.
const NewtonBody *childBody	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.
const NewtonBody *parentBody	-	is the pointer to the parent rigid body, this body can be NULL or any kind of rigid body.

Return

Pointer to the hinge joint.

Remarks

This function creates a hinge and add it to the world. By default joint disables collision with the linked bodies.

Set an update call back to be called when either of the two body linked by the joint is active.

Parameters

const NewtonJoint *Hinge	-	pointer to the joint.
NewtonHingeCallBack callback	-	pointer to the joint function call back.

Return

nothing.

Remarks

if the application wants to have some feedback from the joint simulation, the application can register a function update callback to be call every time any of the bodies linked by this joint is active. This is useful to provide special effects like particles, sound or even to simulate breakable moving parts.

See also

NewtonJointGetUserData, NewtonJointSetUserData

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *Hinge

-

pointer to the joint.

Return

the joint angle relative to the hinge pin.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonHingeSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *Hinge

-

pointer to the joint.

Return

the joint angular velocity relative to the pin axis.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonHingeSetUserCallback

Calculate the angular acceleration needed to stop the hinge at the desired angle.

Parameters

const NewtonJoint *Hinge	-	pointer to the joint.
NewtonHingeSliderUpdateDesc *desc	-	is the pointer to and the Hinge or slide structure.
dFloat angle	-	is the desired hinge stop angle

Return

the relative angular acceleration needed to stop the hinge.

Remarks

this function can only be called from a NewtonHingeCallBack and it can be used by the application to implement hinge limits.

See also

NewtonHingeSetUserCallback

Get the total force asserted over the joint pivot point, to maintain the constraint.

Parameters

const NewtonJoint *Hinge	-	pointer to the joint.
dFloat *force	-	pointer to an array of a least three floats to hold the force value of the joint.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can destroy the joint if the force exceeds some predefined value.

See also

NewtonHingeSetUserCallback

Create a slider joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *pivotPoint	-	is origin of the slider in global space.
const NewtonCollision *pinDir	-	is the line of action of the slider in global space.
const NewtonBody *childBody	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.
const NewtonBody *parentBody	-	is the pointer to the parent rigid body, this body can be NULL or any kind of rigid body.

Return

Pointer to the slider joint.

Remarks

This function creates a slider and add it to the world. By default joint disables collision with the linked bodies.

Set an update call back to be called when either of the two body linked by the joint is active.

Parameters

const NewtonJoint *Slider	-	pointer to the joint.
NewtonSliderCallBack callback	-	pointer to the joint function call back.

Return

nothing.

Remarks

if the application wants to have some feedback from the joint simulation, the application can register a function update callback to be call every time any of the bodies linked by this joint is active. This is useful to provide special effects like particles, sound or even to simulate breakable moving parts.

See also

NewtonJointGetUserData, NewtonJointSetUserData

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *Slider

-

pointer to the joint.

Return

the joint angle relative to the hinge pin.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonSliderSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *Slider

-

pointer to the joint.

Return

the joint angular velocity relative to the pin axis.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonSliderSetUserCallback

Calculate the angular acceleration needed to stop the slider at the desired angle.

Parameters

const NewtonJoint *slider	-	pointer to the joint.
NewtonSliderSliderUpdateDesc *desc	-	is the pointer to the Slider or slide structure.
dFloat distance	-	desired stop distance relative to the pivot point

Return

the relative linear acceleration needed to stop the slider.

Remarks

this function can only be called from a NewtonSliderCallBack and it can be used by the application to implement slider limits.

See also

NewtonSliderSetUserCallback

Get the total force asserted over the joint pivot point, to maintain the constraint.

Parameters

const NewtonJoint *Slider	-	pointer to the joint.
dFloat *force	-	pointer to an array of a least three floats to hold the force value of the joint.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can destroy the joint if the force exceeds some predefined value.

See also

NewtonSliderSetUserCallback

Create a corkscrew joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *pivotPoint	-	is origin of the corkscrew in global space.
const NewtonCollision *pinDir	-	is the line of action of the corkscrew in global space.
const NewtonBody *childBody	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.
const NewtonBody *parentBody	-	is the pointer to the parent rigid body, this body can be NULL or any kind of rigid body.

Return

Pointer to the corkscrew joint.

Remarks

This function creates a corkscrew and add it to the world. By default joint disables collision with the linked bodies.

Set an update call back to be called when either of the two body linked by the joint is active.

Parameters

const NewtonJoint *Corkscrew	-	pointer to the joint.
NewtonCorkscrewCallBack callback	-	pointer to the joint function call back.

Return

nothing.

Remarks

if the application wants to have some feedback from the joint simulation, the application can register a function update callback to be call every time any of the bodies linked by this joint is active. This is useful to provide special effects like particles, sound or even to simulate breakable moving parts.

Remarks

the function NewtonCorkscrewCallBack callback should return a bit field code. if the application does not want to set the joint acceleration the return code is zero if the application only wants to change the joint linear acceleration the return code is 1 if the application only wants to change the joint angular acceleration the return code is 2 if the application only wants to change the joint angular and linear acceleration the return code is 3

See also

NewtonJointGetUserData, NewtonJointSetUserData

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *Corkscrew

-

pointer to the joint.

Return

the joint angle relative to the hinge pin.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonCorkscrewSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *Corkscrew

-

pointer to the joint.

Return

the joint angular velocity relative to the pin axis.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonCorkscrewSetUserCallback

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *Corkscrew

-

pointer to the joint.

Return

the joint angle relative to the corkscrew pin.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonCorkscrewSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *Corkscrew

-

pointer to the joint.

Return

the joint angular velocity relative to the pin axis.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonCorkscrewSetUserCallback

Calculate the angular acceleration needed to stop the corkscrew at the desired angle.

Parameters

const NewtonJoint *Corkscrew	-	pointer to the joint.
NewtonCorkscrewSliderUpdateDesc *desc	-	is the pointer to the Corkscrew or slide structure.
dFloat angle	-	is the desired corkscrew stop angle

Return

the relative angular acceleration needed to stop the corkscrew.

Remarks

this function can only be called from a NewtonCorkscrewCallBack and it can be used by the application to implement corkscrew limits.

See also

NewtonCorkscrewSetUserCallback

Calculate the angular acceleration needed to stop the corkscrew at the desired angle.

Parameters

const NewtonJoint *corkscrew	-	pointer to the joint.
NewtonCorkscrewCorkscrewUpdateDesc *desc	-	is the pointer to the Corkscrew or slide structure.
dFloat distance	-	desired stop distance relative to the pivot point

Return

the relative linear acceleration needed to stop the corkscrew.

Remarks

this function can only be called from a NewtonCorkscrewCallBack and it can be used by the application to implement corkscrew limits.

See also

NewtonCorkscrewSetUserCallback

Get the total force asserted over the joint pivot point, to maintain the constraint.

Parameters

const NewtonJoint *Corkscrew	-	pointer to the joint.
dFloat *force	-	pointer to an array of a least three floats to hold the force value of the joint.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can destroy the joint if the force exceeds some predefined value.

See also

NewtonCorkscrewSetUserCallback

Create a universal joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *pivotPoint	-	is origin of the universal joint in global space.
const NewtonCollision *pinDir0	-	first axis of rotation fixed on childBody body and perpendicular to pinDir1.
const NewtonCollision *pinDir1	-	second axis of rotation fixed on parentBody body and perpendicular to pinDir0.
const NewtonBody *childBody	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.
const NewtonBody *parentBody	-	is the pointer to the parent rigid body, this body can be NULL or any kind of rigid body.

Return

Pointer to the universal joint.

Remarks

This function creates a universal joint and add it to the world. By default joint disables collision with the linked bodies.

Remark

a universal joint is a constraint that restricts twp rigid bodies to be connected to a point fixed on both bodies, while and allowing one body to spin around a fix axis in is own frame, and the other body to spin around another axis fixes on it own frame. Both axis must be mutually perpendicular.

Set an update call back to be called when either of the two body linked by the joint is active.

Parameters

const NewtonJoint *Universal	-	pointer to the joint.
NewtonUniversalCallBack callback	-	pointer to the joint function call back.

Return

nothing.

Remarks

if the application wants to have some feedback from the joint simulation, the application can register a function update callback to be called every time any of the bodies linked by this joint is active. This is useful to provide special effects like particles, sound or even to simulate breakable moving parts.

Remarks

the function NewtonUniversalCallBack callback should return a bit field code. if the application does not want to set the joint acceleration the retur code is zero if the application only wants to change the joint linear acceleration the return code is 1 if the application only wants to change the joint angular acceleration the return code is 2 if the application only wants to change the joint angular and linear acceleration the return code is 3

See also

NewtonJointGetUserData, NewtonJointSetUserData

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *Universal

-

pointer to the joint.

Return

the joint angle relative to the universal pin0.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonUniversalSetUserCallback

Get the relative joint angle between the two bodies.

Parameters

const NewtonJoint *Universal

-

pointer to the joint.

Return

the joint angle relative to the universal pin1.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play a bell sound when the joint angle passes some max value.

See also

NewtonUniversalSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *Universal

-

pointer to the joint.

Return

the joint angular velocity relative to the pin0 axis.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonUniversalSetUserCallback

Get the relative joint angular velocity between the two bodies.

Parameters

const NewtonJoint *Universal

-

pointer to the joint.

Return

the joint angular velocity relative to the pin1 axis.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can play the creaky noise of a hanging lamp.

See also

NewtonUniversalSetUserCallback

Calculate the angular acceleration needed to stop the universal at the desired angle.

Parameters

const NewtonJoint *Universal	-	pointer to the joint.
NewtonUniversalSliderUpdateDesc *desc	-	is the pointer to the Universal or slide structure.
dFloat angle	-	is the desired universal stop angle rotation around pin0

Return

the relative angular acceleration needed to stop the universal.

Remarks

this function can only be called from a NewtonUniversalCallBack and it can be used by the application to implement universal limits.

See also

NewtonUniversalSetUserCallback

Calculate the angular acceleration needed to stop the universal at the desired angle.

Parameters

const NewtonJoint *Universal	-	pointer to the joint.
NewtonUniversalSliderUpdateDesc *desc	-	is the pointer to and the Universal or slide structure.
dFloat angle	-	is the desired universal stop angle rotation around pin1

Return

the relative angular acceleration needed to stop the universal.

Remarks

this function can only be called from a NewtonUniversalCallBack and it can be used by the application to implement universal limits.

See also

NewtonUniversalSetUserCallback

Get the total force asserted over the joint pivot point, to maintain the constraint.

Parameters

const NewtonJoint *Universal	-	pointer to the joint.
dFloat *force	-	pointer to an array of a least three floats to hold the force value of the joint.

Return

nothing.

Remarks

this function can be used during a function update call back to provide the application with some special effect. for example the application can destroy the joint if the force exceeds some predefined value.

See also

NewtonUniversalSetUserCallback

Create a UpVector joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonCollision *pinDir	-	is the aligning vector.
const NewtonBody *body	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.

Return

Pointer to the up vector joint.

Remarks

This function creates an up vector joint. An up vector joint is a constraint that allows a body to translate freely in 3d space, but it only allows the body to rotate around the pin direction vector. This could be use by the application to control a character with physics and collision.

Remark

Since the UpVector joint is a unary constraint, there is not need to have user callback or user data assigned to it. The application can simple hold to the joint handle and update the pin on the force callback function of the rigid body owning the joint.

Get the up vector pin of this joint in global space.

Parameters

const NewtonJoint *upVector	-	pointer to the joint.
dFloat *pin	-	pointer to an array of a least three floats to hold the up vector direction in global space.

Return

nothing.

Remarks

the application ca call this function to read the up vector, this is useful to animate the up vector. if the application is going to animated the up vector, it must do so by applying only small rotation, too large rotation can cause vibration of the joint.

See also

NewtonUpVectorSetUserCallback, NewtonUpVectorSetPin

Set the up vector pin of this joint in global space.

Parameters

const NewtonJoint *upVector	-	pointer to the joint.
dFloat *pin	-	pointer to an array of a least three floats containing the up vector direction in global space.

Return

nothing.

Remarks

the application ca call this function to change the joint up vector, this is useful to animate the up vector. if the application is going to animated the up vector, it must do so by applying only small rotation, too large rotation can cause vibration of the joint.

See also

NewtonUpVectorSetUserCallback, NewtonUpVectorGetPin

Create a user define bilateral joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
in*t maxDOF	-	is the maximum number of degree of freedom controlled by this joint.
NewtonUpVectorCallBack callback	-	pointer to the joint function call back.
const NewtonBody *childBody	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.
const NewtonBody *parentBody	-	is the pointer to the parent rigid body, this body can be NULL or any kind of rigid body.

Remark

Bilateral joint are constraints that can have up to 6 degree of freedoms, 3 linear and 3 angular. By restricting the motion along any number of these degree of freedom a very large number of useful joint between two rigid bodies can be accomplished. Some of the degree of freedoms restriction makes no sense, and also some combinations are so rare that only make sense to a very specific application, the Newton engine implements the more commons combinations like, hinges, ball and socket, etc. However if and application is in the situation that any of the provided joints can achieve the desired effect, then the application can design it own joint.

Remark

User defined joint is a very advance feature that should be look at, only for very especial situations. The designer must be a person with a very good understanding of constrained dynamics, and it may be the case that many trial have to be made before a good result can be accomplished.

Remark

maxDOF is and upper bound as to how many degrees of freedoms the joint can control, usually this value can be 6 for bilateral joints, but it can be higher for special joints like vehicles where by the used of friction clamping the number of rows can be higher. In general the application should determine maxDof correctly, passing an unnecessary excessive value will lead to performance decreased.

Add a linear restricted degree of freedom.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
const dFloat *pivot0	-	pointer of a vector in global space fixed on body zero.
const dFloat *pivot1	-	pointer of a vector in global space fixed on body one.
const dFloat *pin	-	pointer of a unit vector in global space along which the relative position, velocity and acceleration between the bodies will be driven to zero.

Remark

A linear contraint row calculates the Jacobian derivatives and relative acceleration required to enforce the constraint condition at the attachment point and the pin direction considered fixed to both bodies.

Remark

The acceleration is calculated such that the relative linear motion between the two points is zero, the application can afterward override this value to create motors.

Remark

after this function is call and internal DOF index will point to the current row entry in the constraint matrix.

Remark

This function call only be called from inside a NewtonUserBilateralCallBack callback.

See also

NewtonUserJointAddAngularRow,

Add an angular restricted degree of freedom.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat relativeAngleError	-	relative angle error between both bodies around pin axis.
const dFloat *pin	-	pointer of a unit vector in global space along which the relative position, velocity and acceleration between the bodies will be driven to zero.

Remark

An angular contraint row calculates the Jacobian derivatives and relative acceleration required to enforce the constraint condition at pin direction considered fixed to both bodies.

Remark

The acceleration is calculated such that the relative angular motion between the two points is zero, The application can afterward override this value to create motors.

Remark

After this function is called and internal DOF index will point to the current row entry in the constraint matrix.

Remark

This function call only be called from inside a NewtonUserBilateralCallBack callback.

Remark

This function is of not practical to enforce hard constraints, but it is very useful for making angular motors.

See also

NewtonUserJointAddLinearRow, NewtonUserJointAddIndependentAngularRow

set the general linear and angular Jacobian for the desired degree of freedom

Parameters

const NewtonJoint *joint	-	pointer to the joint.
const dFloat *jacobian0	-	pointer of a set of six values defining the linear and angular Jacobian for body0.
const dFloat *jacobian1	-	pointer of a set of six values defining the linear and angular Jacobian for body1.

Remark

In general this function must be used for very special effects and in combination with other joints. it is expected that the user have a knowledge of Constrained dynamics to make a good used of this function. Must typical application of this function are the creation of synchronization or control joints like gears, pulleys, worm gear and some other mechanical control.

Remark

this function set the relative acceleration for this degree of freedom to zero. It is the application responsibility to set the relative acceleration after a call to this function

See also

NewtonUserJointAddLinearRow, NewtonUserJointAddAngularRow

Set the maximum friction value the solver is allow to apply to the joint row.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat friction	-	maximum friction value for this row. It must be a positive value between 0.0 and INFINITY.

Remark

This function will override the default friction values set after a call to NewtonUserJointAddLinearRow or NewtonUserJointAddAngularRow. friction value is context sensitive, if for linear constraint friction is a Max friction force, for angular constraint friction is a max friction is a Max friction torque.

See also

NewtonUserJointSetRowMinimumFriction, NewtonUserJointAddLinearRow, NewtonUserJointAddAngularRow

Set the minimum friction value the solver is allow to apply to the joint row.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat friction	-	friction value for this row. It must be a negative value between 0.0 and -INFINITY.

Remark

This function will override the default friction values set after a call to NewtonUserJointAddLinearRow or NewtonUserJointAddAngularRow. friction value is context sensitive, if for linear constraint friction is a Min friction force, for angular constraint friction is a friction is a Min friction torque.

See also

NewtonUserJointSetRowMaximumFriction, NewtonUserJointAddLinearRow, NewtonUserJointAddAngularRow

Set the value for the desired acceleration for the current constraint row.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat acceleration	-	desired acceleration value for this row.

Remark

This function will override the default acceleration values set after a call to NewtonUserJointAddLinearRow or NewtonUserJointAddAngularRow. friction value is context sensitive, if for linear constraint acceleration is a linear acceleration, for angular constraint acceleration is an angular acceleration.

See also

NewtonUserJointAddLinearRow, NewtonUserJointAddAngularRow

Calculates the row acceleration to satisfy the specified the spring damper system.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat springK	-	desired spring stiffness, it must be a positive value.
dFloat springD	-	desired spring damper, it must be a positive value.

Remark

This function will override the default acceleration values set after a call to NewtonUserJointAddLinearRow or NewtonUserJointAddAngularRow. friction value is context sensitive, if for linear constraint acceleration is a linear acceleration, for angular constraint acceleration is an angular acceleration.

Remark

the acceleration calculated by this function represent the mass, spring system of the form

a = -ks * x

-

kd * v.

Remark

for this function to take place the joint stiffness must be set to a values lower than 1.0

See also

NewtonUserJointSetRowAcceleration, NewtonUserJointSetRowStiffness

Set the maximum percentage of the constraint force that will be applied to the constraint row.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat stiffness	-	row stiffness, it must be a values between 0.0 and 1.0, the default is 0.9.

Remark

This function will override the default stiffness value set after a call to NewtonUserJointAddLinearRow or NewtonUserJointAddAngularRow. the row stiffness is the percentage of the constraint force that will be applied to the rigid bodies. Ideally the value should be 1.0 (100% stiff) but dues to numerical integration error this could be the joint a little unstable, and lower values are preferred.

See also

NewtonUserJointAddLinearRow, NewtonUserJointAddAngularRow, NewtonUserJointSetRowSpringDamperAcceleration

Return the magnitude previews force or torque value calculated by the solver for this contraint row.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
int row	-	index to the constraint row.

Remark

This function can be call for any of the previews row for this particular joint, The application must keep track of the meaning of the row.

Remark

This function can be used to produce special effects like breakable or malleable joints, fro example a hinge can turn into ball and sockect after the force in some of the row excide certain high value.

Store a user defined data value with the joint.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
void *userDataPtr	-	pointer to the user defined user data value.

Return

Nothing.

Remarks

The application can store a user defined value with the Joint. This value can be the pointer to a structure containing some application data for special effect. if the application allocate some resource to store the user data, the application can register a joint destructor to get rid of the allocated resource when the Joint is destroyed

See also

NewtonConstraintCreateJoint, NewtonJointSetDestructor

Retrieve a user defined data value stored with the joint.

Parameters

const NewtonJoint *joint

-

pointer to the joint.

Return

The user defined data.

Remarks

The application can store a user defined value with a joint. This value can be the pointer to a structure to store some game play data for special effect.

See also

NewtonJointSetUserData

Enable or disable collision between the two bodies linked by this joint. The default state is collision disable when the joint is created.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
int state	-	collision state, zero mean disable collision, non zero enable collision between linked bodies.

Return

nothing.

Remarks

usually when two bodies are linked by a joint, the application wants collision between this two bodies to be disabled. This is the default behavior of joints when they are created, however when this behavior is not desired the application can change it by setting collision on. If the application decides to enable collision between jointed bodies, the application should make sure the collision geometry do not collide in the work space of the joint.

Remarks

if the joint is destroyed the collision state of the two bodies linked by this joint is determined by the material pair assigned to each body.

See also

NewtonJointGetCollisionState, NewtonBodySetJointRecursiveCollision

Get the collision state of the two bodies linked by the joint.

Parameters

const NewtonJoint *joint

-

pointer to the joint.

Return

the collision state.

Remarks

usually when two bodies are linked by a joint, the application wants collision between this two bodies to be disabled. This is the default behavior of joints when they are created, however when this behavior is not desired the application can change it by setting collision on. If the application decides to enable collision between jointed bodies, the application should make sure the collision geometry do not collide in the work space of the joint.

See also

NewtonJointSetCollisionState

Set the strength coeficient to be applied to the joint reaction forces.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat stiffness	-	stiffness coeficient, a value between 0, and 1.0, the default value for most joint is 0.9

Return

nothing.

Remarks

Constraint keep bodies together by calculating the exact force necessary to cancel the relative acceleration between one or more common points fixed in the two bodies. The problem is that when the bodies drift apart due to numerical integration inaccuracies, the reaction force work to pull eliminated the error but at the expense of adding extra energy to the system, does violating the rule that constraint forces must be work less. This is a inevitable situation and the only think we can do is to minimize the effect of the extra energy by dampening the force by some amount. In essence the stiffness coefficient tell Newton calculate the precise reaction force by only apply a fraction of it to the joint point. And value of 1.0 will apply the exact force, and a value of zero will apply only 10 percent.

Remark

The stiffness is set to a all around value that work well for most situation, however the application can play with these parameter to make finals adjustment. A high value will make the joint stronger but more prompt to vibration of instability; a low value will make the joint more stable but weaker.

See also

NewtonJointGetStiffness

Get the strength coefficient bing applied to the joint reaction forces.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
dFloat stiffness	-	stiffness coeficient, a value between 0, and 1.0, the default value for most joint is 0.9

Return

stiffness coeficient.

Remarks

Constraint keep bodies together by calculating the exact force necessary to cancel the relative acceleration between one or more common points fixed in the two bodies. The problem is that when the bodies drift apart due to numerical integration inaccuracies, the reaction force work to pull eliminated the error but at the expense of adding extra energy to the system, does violating the rule that constraint forces must be work less. This is a inevitable situation and the only think we can do is to minimize the effect of the extra energy by dampening the force by some amount. In essence the stiffness coefficient tell Newton calculate the precise reaction force by only apply a fraction of it to the joint point. And value of 1.0 will apply the exact force, and a value of zero will apply only 10 percent.

Remark

The stiffness is set to a all around value that work well for most situation, however the application can play with these parameter to make finals adjustment. A high value will make the joint stronger but more prompt to vibration of instability; a low value will make the joint more stable but weaker.

See also

NewtonJointSetStiffness

Register a destructor callback to be called when the joint is about to be destroyed.

Parameters

const NewtonJoint *joint	-	pointer to the joint.
NewtonJointCallBack destructor	-	pointer to the joint destructor callback.

Return

nothing.

Remarks

If application stores any resource with the joint, or the application wants to be notified when the joint is about to be destroyed. The application can register a destructor call back with the joint.

See also

NewtonJointSetUserData

destroy a joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the body.
const NewtonJoint *joint	-	pointer to joint to be destroyed

Return

nothing

Remarks

The application can call this function when it wants to destroy a joint. This function can be used by the application to simulate breakable joints

See also

NewtonConstraintCreateJoint, NewtonConstraintCreateHinge, NewtonConstraintCreateSlider

Create an empty rag doll container.

Parameters

const NewtonWorld *newtonWorld

-

is the pointer to the Newton world.

Return

handle to an empty rag doll container.

Remarks

A rag doll container is the encapsulation of a group of ball and socket joints, under a common object. It provides common functional shared by all joints in the tree like structure. The rag doll object job is to simplify some of the common task that the programmer encounters when it tries to make a rag doll model by connecting joints. It also has some limitations, for example the hierarchy of joints is made of Ball and socket joints, it only support tree like structures of joints, the joints can not by detached from the array once they are added to the rag doll. Rag doll joints are good to make articulated creatures, like humans, monsters, horses, etc. They are good to simulate effects like death of a character in a game.

See also

NewtonDestroyRagDoll

Destroy a ragdoll containers and all it components.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const NewtonRagDoll *ragDoll	-	handle to a rag doll container.

Return

nothing

See also

NewtonCreateRagDoll

Prepare a rag doll object to accept bones and making the skeleton.

Parameters

const NewtonRagDoll *ragDoll

-

handle to a rag doll container.

Return

nothing

Remarks

This function will clean up the rag doll container of any previously added bone. After the constructions process of the rag doll is completed the application should call NewtonRagDollEnd, not doing so will result in unpredictable results.

See also

NewtonRagDollEnd, NewtonRagDollAddBone, SetExtForceAndTorqueCallback, SetTransformCallback

Finalized the rag doll construction process.

Parameters

const NewtonRagDoll *ragDoll

-

handle to a rag doll container.

Return

nothing

Remarks

This function should be called after the constructions process of the rag doll in completed. calling this function without first calling NewtonRagDollBegin will produce unpredictable results.

See also

NewtonRagDollBegin

Add a bone to a rag doll objects.

Parameters

const NewtonRagDoll *ragDoll	-	handle to a rag doll container.
const NewtonRagDollBone *parent	-	handle to the bone parent for this bone. If this is the root bone the parent should be NULL.
void *userData	-	user data value. The application can use this parameter to store the pointer on index into the graphical part representing this bone.
dFloat mass	-	mass of this body part.
const dFloat *matrix	-	pointer to a 4x4 transformation matrix in the local space of the bone. The matrix should be expressed relative to the parent bone.
const NewtonCollision *boneCollision	-	bone collision geometry.
const dFloat size	-	pointer to an array of three dFloat specifying the size of this body part. The first component of the array is interpreted as the length of the bone.

Return

the handle to a Rag doll bone

Remarks

The user data value of a rag doll rigid body is set to the NewtonRagDollBone, Unpredictable result will happens if the application set the user data of a rag doll node rigid body.

Remarks

this function can only be called from inside of a NewtonRagDollBegin/NewtonRagDollEnd pair.

See also

NewtonRagDollBegin

Retrieve a user defined data value stored with the rag doll bone.

Parameters

const NewtonRagDollBone *bone

-

pointer to the bone.

Return

The user defined data.

Remarks

The application can store a user defined value with a rigid body. This value can be the pointer to a structure which is the graphical representation of the bone.

See also

NewtonRagDollAddBone

Assign a transformation event function to a rag doll object.

Parameters

const NewtonRagDoll *ragDoll	-	handle to a rag doll container.
NewtonSetRagDollTransform callback	-	pointer to a function callback is used to update the transformation matrix of the visual object that represents the rag doll.

Return

Nothing.

Remarks

The function NewtonSetRagDollTransform callback is called by the Newton engine every time a visual object that represent a bone of a rag doll has changed. The application can obtain the pointer user data value that points to the visual object. The Newton engine does not call the NewtonSetRagDollTransform callback function for bones that are inactive or have reached a state of stable equilibrium.

Remarks

The user data value of a rag doll rigid body is set to the NewtonRagDollBone, Unpredictable result will happens if the application set the user data of a rag doll node rigid body. The application can get the pointer to the application graphical data by retrieving the user data stored with the NewtonRagDollBone.

Remarks

The matrix should be organized in row-major order (this is the way directX stores matrices). If you are using OpenGL matrices (column-major) you will need to transpose the matrices into a local array, before you pass them to Newton.

Remarks

this function can only be called from inside of a NewtonRagDollBegin/NewtonRagDollEnd pair.

See also

NewtonRagDollBegin, NewtonRagDollAddBone

Assign an event function for applying external force and torque to a Rag doll.

Parameters

const NewtonRagDoll *ragDoll	-	handle to a rag doll container.
NewtonApplyForceAndTorque callback	-	pointer to a function callback used to apply force and torque to a rigid body bone.

Return

Nothing.

Remarks

this function can be seen as a utility function that will call NewtonBodySetForceAndTorqueCallback for every bone of a rag doll object.

Remarks

The user data value of a rag doll rigid body is set to the NewtonRagDollBone, unpredictable result will happens if the application set the user data of a rag doll node rigid body. The application can get the pointer to the application graphical data by retrieving the user data stored with the NewtonRagDollBone.

Remarks

Before the NewtonApplyForceAndTorque callback is called for a body, Newton first clears the net force and net torque for the body.

Remarks

The function NewtonApplyForceAndTorque callback is called by the Newton Engine every time an active body is going to be simulated. The Newton Engine does not call the NewtonApplyForceAndTorque callback function for bodies that are inactive or have reached a state of stable equilibrium.

See also

NewtonRagDollBegin, NewtonRagDollAddBone

Set an id for this particular bone.

Parameters

const NewtonRagDollBone *bone	-	handle to the bone.
int id	-	identifier for this bone.

Return

Nothing.

Remarks

during the construction, the application has the option to set an identifier for each bone. It is good idea to make this identifier unique for the rag doll.

See also

NewtonRagDollAddBone, NewtonRagDollFindBone

Find the first bone with this id in this rag doll.

Parameters

const NewtonRagDoll *ragDoll	-	handle to a rag doll container.
int id	-	identifier for this bone.

Return

the handle to the bone with this identifier. NULL if no bone in the rag doll has this id

Remarks

during the construction, the application has the option to set an identifier for each bone. It is good idea to make this identifier unique for the rag doll. the application can use this id to find particular bones in the rag doll body. This is useful for authoring tolls.

See also

NewtonRagDollBoneSetID

Retrieve the rigid body assigned to this bone.

Parameters

const NewtonRagDollBone *bone

-

handle to the bone.

Return

The rigid body assigned to this bone

Remarks

this function can be used to customized some of the properties of the rigid body assigned to the bone. the application should not override the pointer to TransformCallback or ApplyForceAndTorque of a rigid body assigned to a Rag doll bone. It should call the functions NewtonRagDollSetTransformCallback and NewtonRagDollSetForceAndTorqueCallback instead.

See also

NewtonRagDollAddBone, NewtonRagDollSetTransformCallback, NewtonRagDollSetForceAndTorqueCallback

Set the stop limits for this bone.

Parameters

const NewtonRagDollBone *bone	-	handle to this particular bone. If this parameter is the root bone, then the limits do not have any effect.
const dFloat *coneDir	-	pointer to an array of tree dFloat specifying the direction in global space of the cone limits for this bone.
dFloat minConeAngle	-	minimum value of the cone of the cone limit.
dFloat maxConeAngle	-	maximum value of the cone of the cone limit.
dFloat maxTwistAngle	-	maximum and minimum that this bone is allow to spin around the coneDir.
const dFloat *lateralConeDir	-	this parameter is ignored in this release.
dFloat negativeBilateralConeAngle	-	this parameter is ignored in this release.
dFloat negativeBilateralConeAngle	-	this parameter is ignored in this release.

Remarks

This function set a cone fixed on the frame of the parent of this bone and defining the work space of the bone.

See also

NewtonRagDollBegin

Get the transformation matrix for this bone in the local space of the bone.

Parameters

const NewtonRagDollBone *bone	-	handle to this particular bone. If this parameter is the root bone, then the limits do not have any effect.
dFloat *matrix	-	pointer to a 4x4 transformation matrix to receive the transformation matrix for this bone.

Remarks

the application can call this function from a NewtonSetRagDollTransform to get the transformation matrix for the graphical representation of the bone in local space.

See also

NewtonRagDollSetTransformCallback

Get the transformation matrix for this bone in the global space of the bone.

Parameters

const NewtonRagDollBone *bone	-	handle to this particular bone. If this parameter is the root bone, then the limits do not have any effect.
dFloat *matrix	-	pointer to a 4x4 transformation matrix to receive the transformation matrix for this bone.

Remarks

the application can call this function from a NewtonSetRagDollTransform to get the transformation matrix for the graphical representation of the bone in global space.

See also

NewtonRagDollSetTransformCallback

Create and empty vehicle joint.

Parameters

const NewtonWorld *newtonWorld	-	is the pointer to the Newton world.
const dFloat *upDir	-	is the unit vector defined by the tires pivot points, usually the opposite direction to the gravity vector.
const NewtonBody *body	-	is the pointer to the attached rigid body, this body can not be NULL or it can not have an infinity (zero) mass.

Return

Pointer to the vehicle joint.

Remarks

This joint provides basics functionality for simulating real-time simplistic vehicle dynamics. The joint is not meant to be and accurate and realistic representation of a real vehicle, that is out of the scope of a real-time physics engine. The vehicle is made out of a main rigid body visible to the application and attached to it a set of tires not visible to the application directly as rigid bodies. The tires are connected to the body via rigid wheel joints providing the ability for the tire to spin, have suspension, and turn. The internal vehicle mechanics like transmission, power transfer shaft, suspension mechanism, doors etc. It only models the vehicle body mounted on a set of wheels, with suspension and the ability to roll.

Store a function callback pointer for vehicle update.

Parameters

const NewtonJoint *vehicle	-	pointer to the vehicle joint.
NewtonVehicleTireUpdate update	-	pointer to the callback function.

Return

nothing

Remarks

The only way to control a vehicle is by implementing the vehicle update callback. The application should iterate through each tire applying tire dynamics to each one.

See also

NewtonVehicleGetFirstTireID, NewtonVehicleGetNextTireID

Add a new tire to the vehicle container.

Parameters

const NewtonJoint *vehicle	-	pointer to the vehicle joint.
const dFloat *localMatrix	-	pointer to an array of 16 floats containing the offset of the tire relative to the vehicle body.
const dFloat pin	-	pointer to an array of 3 floats containing the rotation axis of the tire, in the space of the tire.
dFloat mass	-	tire mass, must be much smaller than the vehicle body. ratio of 50:1 to 100:1 are the recommended values.
dFloat width	-	width of the tire, must be smaller than the tire radius.
dFloat radius	-	tire radius.
dFloat suspesionShock	-	parametrized damping constant for a spring, mass, damper system. A value of one corresponds to a critically damped system.
dFloat suspesionSpring	-	parametrized spring constant for a spring, mass, damper system. A value of one corresponds to a critically damped system.
dFloat suspesionLength	-	distance from the tire set position to the upper stop on the vehicle body frame. The total suspension length is twice that.
void *userData	-	pointer to a user define data value. Usually used to store the pointer to the graphical representation of the tire.
int collisionID	-	the collision ID use by the application to identify the tire contacts in a contact callback function.

Return

the tire ID.

Remarks

After the application creates the vehicle joint, it must add the tires. Tires are added one at a time at the graphics set position and with the appropriate. the application should calculate the correct tire parameters, like tire mass, position, width height, spring and damper constants.

See also

NewtonVehicleRemoveTire

Reset all tires velocities to zero.

Parameters

const NewtonJoint *vehicle

-

pointer to the vehicle joint.

Return

nothing.

This function is useful for reposition the vehicle.

Detach and destroy a tire from the vehicle.

Parameters

const NewtonJoint *vehicle	-	pointer to the vehicle joint.
void *tireId	-	tire index to be destroyed.

Return

nothing.

Get the index of the first tire of the vehicle tire set.

Parameters

const NewtonJoint *vehicle

-

pointer to the vehicle joint.

Return

tire index.

Remarks

This function is usually used from inside the vehicle update callback. It is used to iterate through the tire set applying the tire dynamics.

See also

NewtonVehicleGetNextTireID

Get the index of the next tire on the tire set.

Parameters

const NewtonJoint *vehicle	-	pointer to the vehicle joint.
void *tireId	-	index to current tire.

Return

Next tire index, or zero if index tireId was pointing to the last tire in the set.

Remarks

This function is usually used from inside a tire update callback. It is used to iterate through the tire set applying the tire dynamics.

See also

NewtonVehicleGetFirstTireID

Retrieve the pointer to the tire user data.

Parameters

const NewtonJoint *vehicle	-	pointer to the vehicle joint.
void *tireId	-	index to current tire.

Return

tire user data.

Remarks

This function is usually used from the vehicle update callback or from transformation callback of the vehicle body, It can used do set the transformation matrix of the tire graphical representation.