World

NewtonWorld *NewtonCreate()

Create an instance of the Newton world.

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

Return
Pointer to new Newton world.

See also: NewtonDestroy, NewtonDestroyAllBodies

NewtonWorld *NewtonCreateEx(int stackSizeInMegabytes)

Create an instance of the Newton world.

This function does the same as NewtonCreate, except that it accepts an extra argument to specify the stack size for each thread. This is only useful for simulation with very many (ie thousands or more objects). If in doubt, use NewtonCreate as it uses reasonable defaults.

Return
Pointer to new Newton world.
Parameters
  • stackSizeInMegabytes: Assign this much memory to each thread.

See also: NewtonDestroy, NewtonDestroyAllBodies

void NewtonDestroy(const NewtonWorld *const newtonWorld)

Destroy an instance of the Newton world.

This function will destroy the entire Newton world.

Return
Nothing.
Parameters
  • *newtonWorld: Pointer to the Newton world.

See also: NewtonCreate, NewtonDestroyAllBodies

int NewtonGetBroadphaseAlgorithm(const NewtonWorld *const newtonWorld)
void NewtonSelectBroadphaseAlgorithm(const NewtonWorld *const newtonWorld, int algorithmType)
dFloat NewtonGetContactMergeTolerance(const NewtonWorld *const newtonWorld)
void NewtonSetContactMergeTolerance(const NewtonWorld *const newtonWorld, dFloat tolerance)
void NewtonInvalidateCache(const NewtonWorld *const newtonWorld)

Reset all internal engine states.

Call this function whenever you want to create a reproducible simulation from a pre-defined initial condition.

Parameters
  • *newtonWorld: Pointer to the Newton world.

It does not suffice to merely reset the position and velocity of objects. This is because Newton takes advantage of frame-to-frame coherence for performance reasons.

This function must be called outside of a Newton Update.

Note: this kind of synchronization incurs a heavy performance penalty if called during each update.

See also: NewtonUpdate

void NewtonSetJointSerializationCallbacks(const NewtonWorld *const newtonWorld, NewtonOnJointSerializationCallback serializeJoint, NewtonOnJointDeserializationCallback deserializeJoint)
void NewtonGetJointSerializationCallbacks(const NewtonWorld *const newtonWorld, NewtonOnJointSerializationCallback *const serializeJoint, NewtonOnJointDeserializationCallback *const deserializeJoint)
void NewtonSerializeToFile(const NewtonWorld *const newtonWorld, const char *const filename, NewtonOnBodySerializationCallback bodyCallback, void *const bodyUserData)
void NewtonDeserializeFromFile(const NewtonWorld *const newtonWorld, const char *const filename, NewtonOnBodyDeserializationCallback bodyCallback, void *const bodyUserData)
NewtonBody *NewtonFindSerializedBody(const NewtonWorld *const newtonWorld, int bodySerializedID)
int NewtonGetCurrentDevice(const NewtonWorld *const newtonWorld)
int NewtonEnumerateDevices(const NewtonWorld *const newtonWorld)
void NewtonSetCurrentDevice(const NewtonWorld *const newtonWorld, int deviceIndex)
void NewtonGetDeviceString(const NewtonWorld *const newtonWorld, int deviceIndex, char *const vendorString, int maxSize)
void NewtonWorldCriticalSectionLock(const NewtonWorld *const newtonWorld, int threadIndex)

this function block all other threads from executing the same subsequent code simultaneously.

this function should use to present racing conditions when when a call back ins executed form a mutithreaded loop. In general most call back are thread safe when they do not write to object outside the scope of the call back. this means for example that the application can modify values of object pointed by the arguments and or call that function that are allowed to be call for such callback. There are cases, however, when the application need to collect data for the client logic, example of such case are collecting information to display debug information, of collecting data for feedback. In these situations it is possible the the same critical code could be execute at the same time but several thread causing unpredictable side effect. so it is necessary to block all of the thread from executing any pieces of critical code.

Parameters
  • *newtonWorld: Pointer to the Newton world.
  • threadIndex: thread index from whe thsi function is called, zero if call form outsize a newton update

Not calling function NewtonWorldCriticalSectionUnlock will result on the engine going into an infinite loop.

it is important that the critical section wrapped by functions NewtonWorldCriticalSectionLock and NewtonWorldCriticalSectionUnlock* be keep small if the application is using the multi threaded functionality of the engine no doing so will lead to serialization of the parallel treads since only one thread can run the a critical section at a time.

See also: NewtonWorldCriticalSectionUnlock

Return
Nothing.

int NewtonAtomicSwap(int *const ptr, int value)
int NewtonAtomicAdd(int *const ptr, int value)
void NewtonYield()
void NewtonWorldCriticalSectionUnlock(const NewtonWorld *const newtonWorld)

this function block all other threads from executing the same subsequent code simultaneously.

this function should use to present racing conditions when when a call back ins executed form a multi threaded loop. In general most call back are thread safe when they do not write to object outside the scope of the call back. this means for example that the application can modify values of object pointed by the arguments and or call that function that are allowed to be call for such callback. There are cases, however, when the application need to collect data for the client logic, example of such case are collecting information to display debug information, of collecting data for feedback. In these situations it is possible the the same critical code could be execute at the same time but several thread causing unpredictable side effect. so it is necessary to block all of the thread from executing any pieces of critical code.

Parameters
  • *newtonWorld: Pointer to the Newton world.

it is important that the critical section wrapped by functions NewtonWorldCriticalSectionLock and NewtonWorldCriticalSectionUnlock* be keep small if the application is using the multi threaded functionality of the engine no doing so will lead to serialization of the parallel treads since only one thread can run the a critical section at a time.

See also: NewtonWorldCriticalSectionLock

Return
Nothing.

void NewtonSetThreadsCount(const NewtonWorld *const newtonWorld, int threads)

Set the maximum number of threads the engine can use.

The maximum number of threaded is set on initialization to the maximum number of CPU in the system. fixme: this appears to be wrong. It is set to 1.

Return
Nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • threads: Maximum number of allowed threads.

See also: NewtonGetThreadsCount

int NewtonGetThreadsCount(const NewtonWorld *const newtonWorld)

Return the number of threads currently used by the engine.

See also: NewtonSetThreadsCount, NewtonSetMultiThreadSolverOnSingleIsland

Return
Number threads
Parameters
  • *newtonWorld: Pointer to the Newton world.

int NewtonGetMaxThreadsCount(const NewtonWorld *const newtonWorld)

Return the maximum number of threads supported on this platform.

This function will return 1 on single core version of the library. fixme; what is a single core version?

Return
Number threads.
Parameters
  • *newtonWorld: Pointer to the Newton world.

See also: NewtonSetThreadsCount, NewtonSetMultiThreadSolverOnSingleIsland

void NewtonSetMultiThreadSolverOnSingleIsland(const NewtonWorld *const newtonWorld, int mode)

Enable/disable multi-threaded constraint resolution for large islands (disabled by default).

Multi threaded mode is not always faster. Among the reasons are

Return
Nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • mode: 1: enabled 0: disabled (default)

1 - Significant software cost to set up threads, as well as instruction overhead. 2 - Different systems have different cost for running separate threads in a shared memory environment. 3 - Parallel algorithms often have decreased converge rate. This can be as high as half of the of the sequential version. Consequently, the parallel solver requires a higher number of interactions to achieve similar convergence.

It is recommended this option is enabled on system with more than two cores, since the performance gain in a dual core system are marginally better. Your mileage may vary.

At the very least the application must test the option to verify the performance gains.

This option has no impact on other subsystems of the engine.

See also: NewtonGetThreadsCount, NewtonSetThreadsCount

void NewtonDispachThreadJob(const NewtonWorld *const newtonWorld, NewtonJobTask task, void *const usedData)
void NewtonSyncThreadJobs(const NewtonWorld *const newtonWorld)
int NewtonGetMultiThreadSolverOnSingleIsland(const NewtonWorld *const newtonWorld)
void NewtonSetSolverModel(const NewtonWorld *const newtonWorld, int model)

Set the solver precision mode.

n: the solve will execute a maximum of n iteration per cluster of connected joints and will terminnetare regarless of the of the joint recisual acceleration. If it happen that the joints residual acceleration fall below the minimum tolereance 1.0e-5 then the solve will terminar before the numer of ieteration reach N.

Return
Nothing
Parameters
  • *newtonWorld: is the pointer to the Newton world
  • model: model of operation n = number of iteration defual value is 4.

int NewtonGetSolverModel(const NewtonWorld *const newtonWorld)

Get the solver precision mode.

void NewtonSetSolverConvergenceQuality(const NewtonWorld *const newtonWorld, int lowOrHigh)

Set solver block diaginal joint solver mode. lowOrHigh == 0 Solver uses Gauss Seidel algorithm to solve constraints lowOrHigh != 0 Solver use Danzig algorithm to solve constraints

when setting lowOrHigh != 0 this produces highest acuracacy but can be slower.

int NewtonGetSolverConvergenceQuality(const NewtonWorld *const newtonWorld)
void NewtonSetPerformanceClock(const NewtonWorld *const newtonWorld, NewtonGetTimeInMicrosencondsCallback callback)
void NewtonUpdate(const NewtonWorld *const newtonWorld, dFloat timestep)

Advance the simulation by a user defined amount of time.

This function will advance the simulation by the specified amount of time.

Return
Nothing
Parameters
  • *newtonWorld: is the pointer to the Newton world
  • timestep: time step in seconds.

The Newton Engine does not perform sub-steps, nor does it need tuning parameters. As a consequence, the application is responsible for requesting sane time steps.

See also: NewtonInvalidateCache

Return
This function call NewtonCollisionUpdate at the lower level to get the colliding contacts. fixme: is this true? there is no such function.

void NewtonUpdateAsync(const NewtonWorld *const newtonWorld, dFloat timestep)
void NewtonWaitForUpdateToFinish(const NewtonWorld *const newtonWorld)
dFloat NewtonGetLastUpdateTime(const NewtonWorld *const newtonWorld)
void NewtonSetNumberOfSubsteps(const NewtonWorld *const newtonWorld, int subSteps)
int NewtonGetNumberOfSubsteps(const NewtonWorld *const newtonWorld)
void NewtonDestroyAllBodies(const NewtonWorld *const newtonWorld)

Remove all bodies and joints from the Newton world.

This function will destroy all bodies and all joints in the Newton world, but will retain group IDs.

Return
Nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.

Use this function for when you want to clear the world but preserve all the group IDs and material pairs.

See also: NewtonMaterialDestroyAllGroupID

void NewtonSetIslandUpdateEvent(const NewtonWorld *const newtonWorld, NewtonIslandUpdate islandUpdate)

Set a function callback to be call on each island update.

The application can set a function callback to be called just after the array of all bodies making an island of connected bodies are collected. This function will be called just before the array is accepted for contact resolution and integration.

Return
Nothing.
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • islandUpdate: callback function.

The callback function must return an integer 0 or 1 to either skip or process the bodies in that particular island.

Applications can leverage this function to implement an game physics LOD. For example the application can determine the AABB of the island and check it against the view frustum. If the entire island AABB is invisible, then the application can suspend its simulation, even if it is not in equilibrium.

Other possible applications are to implement of a visual debugger, or freeze entire islands for application specific reasons.

The application must not create, modify, or destroy bodies inside the callback or risk putting the engine into an undefined state (ie it will crash, if you are lucky).

See also: NewtonIslandGetBody

NewtonBody *NewtonWorldGetFirstBody(const NewtonWorld *const newtonWorld)

Get the first body in the body in the world body list.

The application can call this function to iterate thought every body in the world.

Return
nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.

The application call this function for debugging purpose See also: NewtonWorldGetNextBody, NewtonWorldForEachBodyInAABBDo, NewtonWorldForEachJointDo

NewtonBody *NewtonWorldGetNextBody(const NewtonWorld *const newtonWorld, const NewtonBody *const curBody)

Get the first body in the general body.

The application can call this function to iterate through every body in the world.

Return
nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • curBody: fixme

The application call this function for debugging purpose

See also: NewtonWorldGetFirstBody, NewtonWorldForEachBodyInAABBDo, NewtonWorldForEachJointDo

void NewtonWorldForEachJointDo(const NewtonWorld *const newtonWorld, NewtonJointIterator callback, void *const userData)

Trigger callback function for each joint in the world.

The application should provide the function NewtonJointIterator callback to be called by Newton for every joint in the world.

Return
nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • callback: The callback function to invoke for each joint.
  • *userData: User data to pass into the callback.

Note that this function is primarily for debugging. The performance penalty for calling it is high.

See also: NewtonWorldForEachBodyInAABBDo, NewtonWorldGetFirstBody

void NewtonWorldForEachBodyInAABBDo(const NewtonWorld *const newtonWorld, const dFloat *const p0, const dFloat *const p1, NewtonBodyIterator callback, void *const userData)

Trigger a callback for every body that intersects the specified AABB.

The application should provide the function NewtonBodyIterator callback to be called by Newton for every body in the world.

Return
nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • *p0: - pointer to an array of at least three floats to hold minimum value for the AABB.
  • *p1: - pointer to an array of at least three floats to hold maximum value for the AABB.
  • callback: application defined callback
  • *userData: pointer to the user defined user data value.

For small AABB volumes this function is much more inefficients (fixme: more or less efficient?) than NewtonWorldGetFirstBody. However, if the AABB contains the majority of objects in the scene, the overhead of scanning the internal Broadphase collision plus the AABB test make this function more expensive.

See also: NewtonWorldGetFirstBody

int NewtonWorldGetVersion()

Return the current library version number.

The version number is a three-digit integer.

Return
version number as an integer, eg 314.

First digit: major version (interface changes among other things) Second digit: major patch number (new features, and bug fixes) Third Digit: minor bug fixed patch.

int NewtonWorldFloatSize()

Return the size of a Newton dFloat in bytes.

Return
sizeof(dFloat)

void NewtonWorldSetUserData(const NewtonWorld *const newtonWorld, void *const userData)

Store a user defined data value with the world.

The application can attach custom data to the Newton world. Newton will never look at this data.

Return
Nothing.
Parameters
  • *newtonWorld: is the pointer to the newton world.
  • *userData: pointer to the user defined user data value.

The user data is useful for application developing object oriented classes based on the Newton API.

See also: NewtonBodyGetUserData, NewtonWorldSetUserData, NewtonWorldGetUserData

void *NewtonWorldGetUserData(const NewtonWorld *const newtonWorld)

Retrieve the user data attached to the world.

See also: NewtonBodySetUserData, NewtonWorldSetUserData, NewtonWorldGetUserData

Return
Pointer to user data.
Parameters
  • *newtonWorld: Pointer to the Newton world.

void NewtonWorldSetDestructorCallback(const NewtonWorld *const newtonWorld, NewtonWorldDestructorCallback destructor)

Specify a custom destructor callback for destroying the world.

The application may specify its own world destructor.

Parameters
  • *newtonWorld: Pointer to the Newton world.
  • destructor: function poiter callback

See also: NewtonWorldSetDestructorCallback, NewtonWorldGetUserData

NewtonWorldDestructorCallback NewtonWorldGetDestructorCallback(const NewtonWorld *const newtonWorld)

Return pointer to destructor call back function.

See also: NewtonWorldGetUserData, NewtonWorldSetDestructorCallback

Parameters
  • *newtonWorld: Pointer to the Newton world.

void NewtonWorldSetCollisionConstructorDestructorCallback(const NewtonWorld *const newtonWorld, NewtonCollisionCopyConstructionCallback constructor, NewtonCollisionDestructorCallback destructor)
void *NewtonWorldGetListenerUserData(const NewtonWorld *const newtonWorld, void *const listener)
NewtonWorldListenerBodyDestroyCallback NewtonWorldListenerGetBodyDestroyCallback(const NewtonWorld *const newtonWorld, void *const listener)
void NewtonWorldListenerSetBodyDestroyCallback(const NewtonWorld *const newtonWorld, void *const listener, NewtonWorldListenerBodyDestroyCallback bodyDestroyCallback)
void *NewtonWorldAddPreListener(const NewtonWorld *const newtonWorld, const char *const nameId, void *const listenerUserData, NewtonWorldUpdateListenerCallback update, NewtonWorldDestroyListenerCallback destroy)
void *NewtonWorldGetPreListener(const NewtonWorld *const newtonWorld, const char *const nameId)
void *NewtonWorldAddPostListener(const NewtonWorld *const newtonWorld, const char *const nameId, void *const listenerUserData, NewtonWorldUpdateListenerCallback update, NewtonWorldDestroyListenerCallback destroy)
void *NewtonWorldGetPostListener(const NewtonWorld *const newtonWorld, const char *const nameId)
int NewtonWorldGetBodyCount(const NewtonWorld *const newtonWorld)

Return the total number of rigid bodies in the world.

Return
Number of rigid bodies in the world.
Parameters
  • *newtonWorld: Pointer to the Newton world.

int NewtonWorldGetConstraintCount(const NewtonWorld *const newtonWorld)

Return the total number of constraints in the world.

Return
number of constraints.
Parameters
  • *newtonWorld: pointer to the Newton world.

void NewtonWorldRayCast(const NewtonWorld *const newtonWorld, const dFloat *const p0, const dFloat *const p1, NewtonWorldRayFilterCallback filter, void *const userData, NewtonWorldRayPrefilterCallback prefilter, int threadIndex)

Shoot ray from point p0 to p1 and trigger callback for each body on that line.

The ray cast function will trigger the callback for every intersection between the line segment (from p0 to p1) and a body in the world.

Return
nothing
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • *p0: - pointer to an array of at least three floats containing the beginning of the ray in global space.
  • *p1: - pointer to an array of at least three floats containing the end of the ray in global space.
  • filter: Callback function for each hit during the ray scan.
  • *userData: user data to pass along to the filter callback.
  • prefilter: user defined function to be called for each body before intersection.
  • threadIndex: Index of thread that called this function (zero if called form outsize a newton update).

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.

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.

if prefilter is not NULL, Newton will call the application right before executing the intersections between the ray and the primitive. if the function returns zero the Newton will not ray cast the primitive. passing a NULL pointer will ray cast the. The application can use this implement faster or smarter filters when implementing complex logic, otherwise for normal all ray cast this parameter could be NULL.

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.

See also: NewtonWorldConvexCast

int NewtonWorldConvexCast(const NewtonWorld *const newtonWorld, const dFloat *const matrix, const dFloat *const target, const NewtonCollision *const shape, dFloat *const param, void *const userData, NewtonWorldRayPrefilterCallback prefilter, NewtonWorldConvexCastReturnInfo *const info, int maxContactsCount, int threadIndex)

cast a simple convex shape along the ray that goes for the matrix position to the destination and get the firsts contacts of collision.

passing and value of NULL in info an dzero in maxContactsCount will turn thos function into a spcial Ray cast where the function will only calculate the hitParam at the momenet of contacts. tshi si one of the most effiecnet way to use thsio function.

Return
the number of contact at the intesection point (a value equal o lower than maxContactsCount. variable hitParam will be set the uintesation parameter an the momen of impact.
Parameters
  • *newtonWorld: Pointer to the Newton world.
  • *matrix: pointer to an array of at least three floats containing the beginning and orienetaion of the shape in global space.
  • *target: pointer to an array of at least three floats containing the end of the ray in global space.
  • shape: collision shap[e use to cat the ray.
  • param: pointe to a variable the will contart the time to closet aproah to the collision.
  • *userData: user data to be passed to the prefilter callback.
  • prefilter: user define function to be called for each body before intersection.
  • *info: pointer to an array of contacts at the point of intesections.
  • maxContactsCount: maximun number of contacts to be conclaculated, the variable sould be initialized to the capaciaty of info
  • threadIndex: thread index from whe thsi function is called, zero if call form outsize a newton update

these function is similar to NewtonWorldRayCast but instead of casting a point it cast a simple convex shape along a ray for maoprix.m_poit to target position. the shape is global orientation and position is set to matrix and then is swept along the segment to target and it will stop at the very first intersession contact.

for case where the application need to cast solid short to medium rays, it is better to use this function instead of casting and array of parallel rays segments. examples of these are: implementation of ray cast cars with cylindrical tires, foot placement of character controllers, kinematic motion of objects, user controlled continuous collision, etc. this function may not be as efficient as sampling ray for long segment, for these cases try using parallel ray cast.

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.

if prefilter is not NULL, Newton will call the application right before executing the intersections between the ray and the primitive. if the function returns zero the Newton will not ray cast the primitive. The application can use this callback to implement faster or smarter filters when implementing complex logic, otherwise for normal all ray cast this parameter could be NULL.

See also: NewtonWorldRayCast

int NewtonWorldCollide(const NewtonWorld *const newtonWorld, const dFloat *const matrix, const NewtonCollision *const shape, void *const userData, NewtonWorldRayPrefilterCallback prefilter, NewtonWorldConvexCastReturnInfo *const info, int maxContactsCount, int threadIndex)
NewtonBody *NewtonIslandGetBody(const void *const island, int bodyIndex)

Retrieve body by index from island.

This function can only be called from an island update callback.

Return
requested body. fixme: does it return NULL on error?
Parameters
  • island: Pointer to simulation island.
  • bodyIndex: Index of body on current island.

See also: NewtonSetIslandUpdateEvent

void NewtonIslandGetBodyAABB(const void *const island, int bodyIndex, dFloat *const p0, dFloat *const p1)

Return the AABB of the body on this island

This function can only be called from an island update callback.

Parameters
  • island: Pointer to simulation island.
  • bodyIndex: index to the body in current island.
  • p0: - fixme
  • p1: - fixme

See also: NewtonSetIslandUpdateEvent