Newton SDK DBPro Wrapper v1.32

By Walaber
All Coding between 1.31-1.32B by Kjelle
Updated to 1.53 by Tiresius

World Interface Commands

NDB_NewtonCreate

syntax: NDB_NewtonCreate

no values passed to this function

returns: nothing

Comments: This command initialized the entire Newton system, and prepares for adding Rigid Bodies. You must call this function before any other Newton functions.

NDB_NewtonDestroy

syntax: NDB_NewtonDestroy

no values passed to this function

returns: nothing

Comments: Destroys the entire Newton world. If any rigid bodies or joints exist, they will be destroyed. If rigid bodies have the NDB_NewtonBodySetDestructorCallback command called, the DBPro object representing the body will also be automatically deleted.

NDB_NewtonSetSolverModel

syntax: NDB_NewtonSetSolverModel (int)

int SolverModel

returns: nothing

Comments: 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.

v1.31

NDB_NewtonSetFrictionModel

syntax: NDB_NewtonSetFrictionModel (int)

int FrictionModel

returns: nothing

Comments: This function allows the application to chose between and exact or an adaptive coulumb 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.

v1.31

NDB_NewtonSetPlatformArchitecture

syntax: NDB_NewtonSetPlatformArchitecture (int)

int Floating point flag

returns: nothing

Comments: 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
The engine 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.

v1.53

NDB_NewtonUpdate

syntax: NDB_NewtonUpdate [timestep]

timestep amount of time in seconds (float)

returns: nothing

Comments: This function advances the Newton world by the amount of seconds provided. If no time value is provided, the wrapper uses an internal timer to automatically update for you. By specifying your own timestep, you can create special effects like slow-motion, etc.

NDB_NewtonUpdate update by amount of time since last call to the function.
NDB_NewtonUpdate 0.05 update by value of 0.05 seconds.

NDB_NewtonSetMinimumFrameRate

syntax: NDB_NewtonSetMinimumFrameRate framerate

framerate minimum frame rate (float 20-1000)

returns: nothing

Comments: Limited to values between 20 and 1000. Default is 60. If the framerate drops below this number, Newton will perform substeps to maintain physics accuracy.

NDB_NewtonSetMinimumFrameRate 30 set minimum framerate to 30fps.

NDB_NewtonGetTimeStep

syntax: float = NDB_NewtonGetTimeStep()

returns: Return the correct time step for this simulation update.

Comments: This application can be used to get the correct siulation time step.

v1.31

NDB_NewtonDestroyAllBodies

syntax: NDB_NewtonDestroyAllBodies

no values passed to this function

returns: nothing

Comments: Removes all rigid bodies from the Newton world. If rigid bodies have the NDB_NewtonBodySetDestructorCallback command called, the DBPro object representing the body will also be automatically deleted.

NDB_NewtonSetWorldSize

syntax: NDB_NewtonSetWorldSize

(vector 1) min point of the world

(vector 2) max point of the world

returns: nothing

Comments: The Newton World is of a fixed size. You can set the size of the world with this function. The default is {-100, -100, -100} to {100, 100, 100}. This function uses the values set in temp vector 1 for the min point, and temp vector 2 for the max point.
PLEASE NOTE: It is very important to set the World Size or various functions in Newton may not work accurately or predictably.

NDB_SetVector 1, -150.0, -50.0, -150.0 set temp vector 1.
NDB_SetVector 2, 150.0, 50.0, 150.0 set temp vector 2.
NDB_NewtonSetWorldSize set the world size based on the above points.

NDB_NewtonSetBodyLeaveWorldEvent

syntax: NDB_NewtonSetBodyLeaveWorldEvent flag

flag 1 = destroy body

returns: nothing

Comments: Sets how to handle any body that has left the bounds of the Newton world. a flag of "1" means to destroy the body. And other number will simply ignore the object.

NDB_NewtonWorldFreezeBody

syntax: NDB_NewtonWorldFreezeBody body

body index of the rigid body (integer)

returns: nothing

Comments: Removes the rigid body from the active list, effectively "freezing" it in space.

NDB_NewtonWorldUnfreezeBody

syntax: NDB_NewtonWorldUnfreezeBody body

body index of the rigid body (integer)

returns: nothing

Comments: Puts the rigid body back into the active list, "unfreezing" it.

NDB_NewtonWorldRayCast

syntax: dist = NDB_NewtonWorldRayCast( [flag] )

	flag	flag for type of ray cast to use. 1=closest massed body, 2=closest massless body (integer) *optional
	(vector 1)	temp vector used for passing values
	(vector 2)	temp vector used for passing values

returns: distance to the found body (float).

Comments: This is a general Raycast function for the Newton rigid bodies... you might think of it as a Newton "intersect object" command. Before calling this command, you must fill the temp vectors 1 and 2 with the start and end points of the ray you wish to check. the returned value is an interpolation along this line. for example, if the collision occurred half way down the line, the function will return a value of 0.5. if no collision is returned, a value greater than 1.0 is returned.

This command accepts a few different flags to adjust how the raycast works. called with no flag, the command will find the closest body, regardless of what kind of rigid body it is.

Calling with a flag of ",1" specifies for the system to only look for rigid bodies with a mass value > 0.

calling with a flag of ",2" specifies for the system to only look for rigid bodies with a mass EQUAL to 0.

Although the distance interpolation is returned, this function also returns some other information, including the rigid body found, and the normal of the collision. you can get this data with the NDB_RayCastGetBody and NDB_RayCastGetNormal commands.

NDB_NewtonWorldRayCastAllBodies

syntax: int = NDB_NewtonWorldRayCastAllBodies()

	(vector 1)	temp vector used for passing values
	(vector 2)	temp vector used for passing values

returns: number of bodies hit by the ray (integer)

The returned value is the number of bodies hit by the ray in total. you can then call the NDB_RayCastGetBody, NDB_RayCastGetDist, and NDB_RayCastGetNormal commands for each of these bodies to gather information abour every body hit by the ray.

NDB_RayCastGetBody

syntax: int = NDB_RayCastGetBody( [index] )

index

index for what ray cast data to retrieve *optional

returns: ID of rigid body hit by the ray (integer)

Comments: This command returns the rigid body hit by the ray. If you have called NDB_NewtonWorldRayCast before this, call this command with no index value, or a value of "1", as only 1 body is found. If you used the NDB_NewtonWorldRayCastAllBodies command, you can pass any value between 1 and the number of bodies found.

NDB_RayCastGetDist

syntax: float = NDB_RayCastGetDist( [index] )

index

index for what ray cast data to retrieve *optional

returns: distance to the body hit by the ray (float)

Comments: This command returns the distance (value between 0.0 and 1.0) to the rigid body hit by the ray.

If you have called NDB_NewtonWorldRayCast before this, call this command with no index value, or a value of "1", as only 1 body is found. If you used the NDB_NewtonWorldRayCastAllBodies command, you can pass any value between 1 and the number of bodies found.

NDB_RayCastGetNormal

syntax: NDB_RayCastGetNormal [index]

	index	index for what ray cast data to retrieve *optional
	(vector 1)	temp vector used for returning values.

returns: nothing.

Comments: This command returns the normal body at the ray collision point. It fills the internal temp vector 1 with the normal.

NDB_NewtonDestroyJoint

syntax: NDB_NewtonDestroyJoint joint_id

joint_id index of the joint to destroy (integer)

returns: nothing

Comments: Destroys a joint from the world. the joint_id value is the value returned by the function that created the joint (NDB_NewtonConstraintCreateBall, NDB_NewtonConstraintCreateHinge, NDB_NewtonConstraintCreateSlider)

NDB_NewtonCollisionCollide

syntax: count = NDB_NewtonCollisionCollide( col1, col2 )

col1 index of collision1 (integer)

col2 index of collision2 (integer)

(temp vector 1) temp vector used to pass values.

(temp vector 2) temp vector used to pass values.

(temp vector 3) temp vector used to pass values.

(temp vector 4) temp vector used to pass values.

returns: number of contacts found (integer)

Comments: This is a way to access Newton's impressive collision detection system without the physics. You can use this for your own general collision tests, such as zone testing, etc. You call this function by passing the indices to 2 collision geometries, made from the NDB_NewtonCreate... commands (NDB_NewtonCreateBox for example). then, you fill the tmp vectors like so:

temp vector 1 - position of col1
temp vector 2 - rotation of col1
temp vector 3 - position of col2
temp vector 4 - rotation of col2

the function returns an integer, which is the the number of contacts found between the collision geometries. a return value of zero means no collision was found.
After calling this function, you can call the following functions with any number between 1 and the return value to gather more information about the collision detected:
NDB_GetCollisionContact
NDB_GetCollisionNormal
NDB_GetCollisionPenetration

NDB_GetCollisionContact

syntax: NDB_GetCollisionContact index

index index to collision data (integer)

(temp vector 1) temp vector used to return values.

returns: nothing

Comments: This function fills temp vector 1 with the contact point found by the NDB_NewtonCollisionCollide command. You must pass a value between 1 and the return value of that command to get meaningful data.

NDB_GetCollisionNormal

syntax: NDB_GetCollisionNormal index

index index to collision data (integer)

(temp vector 1) temp vector used to return values.

returns: nothing

Comments: This function fills temp vector 1 with the contact normal found by the NDB_NewtonCollisionCollide command. You must pass a value between 1 and the return value of that command to get meaningful data.

NDB_GetCollisionPenetration

syntax: float = NDB_GetCollisionPenetration( index )

index index to collision data (integer)

returns: penetration distance (float)

Comments: This function returns the penetration distance found by the NDB_NewtonCollisionCollide command. You must pass a value between 1 and the return value of that command to get meaningful data.