Newton SDK DBPro Wrapper v1.53

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

Main Index of Commands

Wrapper Specific Commands

NDB_GetVersion
syntax: float = NDB_GetVersion()
no values passed to this function
returns: float value containing current wrapper version.

NDB_NewtonWorldGetVersion
syntax: float = NDB_NewtonWorldGetVersion()
no values passed to this function

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

NDB_GetElapsedTimeInSec
syntax: float = NDB_GetElapsedTimeInSec()
no values passed to this function
returns: float value containing time elapsed since last call to the function (in seconds)
Comments: This is a simple function using the high-resolution timer. You can of course use the timer() function in DBPro, but this function saves some time by converting to seconds for you.

NDB_SetVector
syntax: NDB_SetVector [vec_num,] x, y, z [,w]
vec_num index of vector to fill (integer 1-4) *optional
x 1st value in the vector (float)
y 2nd value in the vector (float)
z 3rd value in the vector (float)
w 4th value in the vector (float) *optional
returns: nothing
Comments: Many Newton functions require you to pass in a 3D vector (sometimes even 2), along with others. There are also many Newton functions that return a vector. Because DBPro can't have a function return more than one number, there is a temporary vector system built into the wrapper. The system has 4 internal vectors that can be used for temporary number storage. This command sets the vector to a set value. You can specify what vector to fill (1-4) first, followed by the x, y, and z values. an optional 4th value (w) is also available. If you don't specify a vector number, vector number 1 is used by default. If you don't specify a "w" value, 1.0 is used by default.
NDB_SetVector 1.0, 2.0, 3.0 (sets vector number 1 to {x=1.0, y=2.0, z=3.0, w=1.0}
NDB_SetVector 2, 1.0, 2.0, 3.0, 4.0 (sets vector number 2 to {x=1.0, y=2.0, z=3.0, w=4.0}

NDB_GetVector_X
syntax: float = NDB_GetVector_X( [vec_num] )
vec_num index of vector (integer 1-4) *optional
returns: float containing the X component of the vector.
Comments: if no vector is specified, vector 1 is used.
x1# = NDB_GetVector_X() returns x value of temp vector 1
x3# = NDB_GetVector_X(3) returns x value of temp vector 3

NDB_GetVector_Y
syntax: float = NDB_GetVector_Y( [vec_num] )
vec_num index of vector (integer 1-4) *optional
returns: float containing the Y component of the vector.
Comments: if no vector is specified, vector 1 is used.
y1# = NDB_GetVector_Y() returns y value of temp vector 1
y3# = NDB_GetVector_Y(3) returns y value of temp vector 3

NDB_GetVector_Z
syntax: float = NDB_GetVector_Z( [vec_num] )
vec_num index of vector (integer 1-4) *optional
returns: float containing the Z component of the vector.
Comments: if no vector is specified, vector 1 is used.
z1# = NDB_GetVector_Z() returns z value of temp vector 1
z3# = NDB_GetVector_Z(3) returns z value of temp vector 3

NDB_GetVector_W
syntax: float = NDB_GetVector_W( [vec_num] )
vec_num index of vector (integer 1-4) *optional
returns: float containing the W component of the vector.
Comments: if no vector is specified, vector 1 is used.
w1# = NDB_GetVector_W() returns w value of temp vector 1
w3# = NDB_GetVector_W(3) returns w value of temp vector 3

NDB_GetMatrix
syntax: NDB_GetMatrix
nothing passed to this function.
returns: nothing
Comments: Some Newton functions return an entire matrix. These functions, when called by the wrapper, will fill the temp matrix with the return data. To access this data in DBPro, call this function. It will fill all 4 internal vectors with the matrix data. Then use the NDB_GetVector_X(), NDB_GetVector_Y(), NDB_GetVector_Z(), NDB_GetVector_W() commands to access the individual values. Vector 1 = top row -> Vector 4 = position row.
NDB_GetMatrix fill temp vectors with matrix data.
posx# = NDB_GetVector_X(4) get the x position stored in the matrix.

NDB_SetMatrix
syntax: NDB_SetMatrix
Contents of Temp Vector 1-4.
returns: nothing
Comments: This function fills the matrix with the Temp vector data.

NDB_BuildMatrix
syntax: NDB_BuildMatrix [ rx, ry, rz, tx, ty, tz ]
rx x rotation (float) *optional
  ry y rotation (float) *optional
  rz z rotation (float) *optional
  tx x translation (float) *optional
  ty y translation (float) *optional
  tz z translation (float) *optional
returns: nothing
Comments: This is a utility command that builds a matrix in one simple command.  You pass it the rotation information (in degrees) along with the translation information, and it fills the internal temp matrix.  This can make setting up rigid bodies and ragdoll bones much simpler. If no values are passed, the function uses the contents of temp vector 1 for the rotation values, and the contents of temp vector 2 for the position data.
build a matrix with rotation (x = 90,y = 0,z = 0) and position (x = 15,y = 10,z = 0):
NDB_BuildMatrix 90.0, 0.0, 0.0, 15.0, 10.0, 0.0

NDB_NormalizeVector
syntax: NDB_NormalizeVector [vec_num]
vec_num index of vector (integer 1-4) *optional
returns: nothing.
Comments: normalizes the specified vector into a unit vector.  If no vector is specified, temp vector 1 is assumed.

NDB_RotateVector
syntax: NDB_RotateVector [vec_num]
vec_num index of vector (integer 1-4) *optional
returns: nothing.

Comments:

Rotates the specified vector by the rotation matrix ( the temp matrix is used, setup a rotation matrix with the NDB_BuildMatrix

command ).

(ROTATION)
NDB_RotateVector / NDB_UnrotateVector

(TRANSLATION)
NDB_TransformVector / NDB_UntransformVector

Think about these commands like this:

(ROTATION)
the vector you pass in represents a direction in LOCAL space. for example, a velocity of (1,0,0) which means a velocity in the local X direction.
now let's say you need to know this in GLOBAL coordinates. you would do this:

NDB_NewtonBodyGetMatrix ShipBody
NDB_SetVector 1,0,0
NDB_RotateVector 1
newx# = NDB_GetVector_X()
newy# = NDB_GetVector_Y()
newz# = NDB_GetVector_Z()

newx,newy,newz are now pointing along the X axis of the body, but in world space.



(TRANSFORMATION)
This is similar, but the vector does not represent a direction, but a point in local space. for example, let's say you have a jetpack at the point (0,2,-5) on your model. now your model is somewhere else in space, rotated, moved, etc. what is the global location of the jetpack? do this:

NDB_NewtonBodyGetMatrix PlayerBody
NDB_SetVector 0,2,-5
NDB_TransformVector 1
newx# = NDB_GetVector_X()
newy# = NDB_GetVector_Y()
newz# = NDB_GetVector_Z()

newx,newy,newz are the global location of the jetpack.



in other words, these commands allow you to get from LOCAL to GLOBAL space, and back again. use the "un" versions of the commands to do the exact opposite.

for example say you detected a ray collision on a body. of course the RayCast system returns global coordinates. but you want to know this point in LOCAL coordinates of the body. you use the UntransformVector command.

 v 1.31

NDB_UnrotateVector
syntax: NDB_UnrotateVector [vec_num]
vec_num index of vector (integer 1-4) *optional
returns: nothing.

Comments: un-rotates the specified vector by the rotation matrix ( the temp matrix is used, setup a rotation matrix with the NDB_BuildMatrix command ).

See comments above for more in depth explanation.

 v 1.31

NDB_TransformVector
syntax: NDB_TranslateVector [vec_num]
vec_num index of vector (integer 1-4) *optional
returns: nothing.

Comments: translates the specified vector by the rotation matrix ( the temp matrix is used, setup a rotation matrix with the NDB_BuildMatrix command ).

See comments above for more in depth explanation.

 v 1.31

NDB_UntransformVector
syntax: NDB_UntranslateVector [vec_num]
vec_num index of vector (integer 1-4) *optional
returns: nothing.

Comments: un-translates the specified vector by the rotation matrix ( the temp matrix is used, setup a rotation matrix with the NDB_BuildMatrix command ).

See comments above for more in depth explanation.

 v 1.31

NDB_SetStandardGravity
syntax: NDB_SetStandardGravity
(vector 1) vector data used to describe acceleration due to gravity
returns: nothing
Comments: Sets the standard gravity to be used if a specific gravity is not specified for a body. This force will only be applied if the NDB_BodySetGravity command is called for the body. See that command for more details.
NDB_SetVector 0.0, -9.8, 0.0
NDB_SetStandardGravity - sets standard acceleration due to gravity to -9.8 units / second.

NDB_GetStandardGravity
syntax: NDB_GetStandardGravity
(vector 1) vector data used to describe acceleration due to gravity
returns: nothing
Comments: Fills temp vector 1 with the Standard gravity set for the world. This force will only be applied if the NDB_BodySetGravity command is called for the body. See that command for more details.

NDB_SetStandardLiquid
syntax: NDB_SetStandardLiquid f_density, l_visc, a_visc
f_density fluid density (float)
  l_visc linear viscosity (float)
  a_visc angular viscosity (float)
  (vector 1) vector data used to describe acceleration due to gravity
returns: nothing
Comments: Sets the standard values for buoyancy forces, describing the density and viscosity of the liquid.  make sure to fill temp vector 1 with the gravitational vector for the liquid as well.

NDB_GetStandardLiquid
syntax: NDB_GetStandardLiquid
  (vector 1)

temp vector used to return values
  (vector 2) temp vector used to return values
returns: nothing

Comments: returns the standard liquid settings for the world.  like so:

temp vector 1
x = fluid density
y = linear viscosity
z = angular viscosity

temp vector 2 = gravity vector

NDB_CalculateMISphereSolid
syntax: NDB_CalculateMISphereSolid mass, radius
mass mass of the body (float)
radius radius of the sphere (float)
(vector 1) temp vector used for return values.
returns: nothing
Comments: Fills temp vector 1 with the Moment of Inertia for a Solid Sphere of the specified size. You can plug these values into the NDB_NewtonBodySetMassMatrix function to achieve more realistic rigid body simulation.

NDB_CalculateMISphereHollow
syntax: NDB_CalculateMISphereHollow mass, radius
mass mass of the body (float)
radius radius of the sphere (float)
(vector 1) temp vector used for return values.
returns: nothing
Comments: Fills temp vector 1 with the Moment of Inertia for a Hollow Sphere of the specified size. You can plug these values into the NDB_NewtonBodySetMassMatrix function to achieve more realistic rigid body simulation.

NDB_CalculateMIBoxSolid
syntax: NDB_CalculateMIBoxSolid mass [, width, height, depth]
mass mass of the body (float)
width width of the box (float) *optional
height height of the box (float) *optional
depth depth of the box (float) *optional
(vector 1) temp vector used for return values.
returns: nothing
Comments: Fills temp vector 1 with the Moment of Inertia for a Solid Box of the specified size. If no size is specified, the contents of temp vector 1 are used. You can plug these values into the NDB_NewtonBodySetMassMatrix function to achieve more realistic rigid body simulation. If no initial size is specified, the contents of temp vector 1 are used.

NDB_CalculateMICubeSolid
syntax: NDB_CalculateMICubeSolid mass, size
mass mass of the body (float)
size size of the body (float)
(vector 1) temp vector used for return values.
returns: nothing
Comments: Fills temp vector 1 with the Moment of Inertia for a Solid Cube of the specified size. You can plug these values into the NDB_NewtonBodySetMassMatrix function to achieve more realistic rigid body simulation.

NDB_CalculateMICylinderSolid
syntax: NDB_CalculateMICylinderSolid mass, radius, height
mass mass of the body (float)
radius radius of the body (float)
height height of the body (float)
(vector 1) temp vector used for return values.
returns: nothing
Comments: Fills temp vector 1 with the Moment of Inertia for a Solid Cylinder of the specified size. You can plug these values into the NDB_NewtonBodySetMassMatrix function to achieve more realistic rigid body simulation. NOTE - the cylinder is assumed to be aligned standing on the X axis. in other words, the height value refers to the X axis of the object, and the radius value refers to the Y and Z axis.

NDB_GetCollisionBodyToBody
syntax: int = NDB_GetCollisionBodyToBody( body1, body2 )
body1 index of rigid body1 (int)
body2 index of rigid body2 (int)
returns: index to the collision data (0 if no collision)
Comments: The wrapper will record collision data for any 2 materials you set. Use this command to check it two bodies (presumably of the materials you set) have collided. The function will return an integer > 0 if there has been a collision. pass this integer into the NDB_GetCollisionDatafunction to retrieve detailed collision data.

NDB_GetCollisionBodyToMaterial
syntax: int = NDB_GetCollisionBodyToMaterial( body, materialID )
body index of rigid body (int)
materialID index of material group ID (int)
returns: index to the collision data (0 if no collision)
Comments: The wrapper will record collision data for any 2 materials you set. Use this command to check if a rigid body and any bodies of the other material have collided. The function will return an integer > 0 if there has been a collision. pass this integer into the NDB_GetCollisionDatafunction to retrieve detailed collision data, including the 2nd body involved in the collision, through the NDB_GetCollisionBody.

NDB_GetCollisionData
syntax: NDB_GetCollisionData index
index index to collision data (int)
returns: nothing
Comments: this will fill the temp vectors with detailed information about the collision found by the NDB_GetCollision command. Data returned:
temp vector 1 [x,y,z] - position of the collision in global space.
temp vector 2 [x,y,z] - normal vector of the collision.
temp vector 2 [w] - speed of collision along normal vector.
temp vector 3 [x,y,z] - first tangent vector of the collision.
temp vector 3 [w] - speed of collision along first tangent vector.
temp vector 4 [x,y,z] - second tangent vector of the collision.
temp vector 4 [w] - speed of collision along second tangent vector.

NDB_GetCollisionBody
syntax: body = NDB_GetCollisionBody( index, body )
index index to collision data (int)
  body index of collision body *1-2 (int)
returns: nothing
Comments: this will return the index to a body involved in the collision.  You can get the bodies involved in the collision by passing a 1 or 2 into the second parameter of the function.

NDB_DebugDrawNewtonLines
syntax: NDB_DebugDrawNewtonLines
returns: nothing.

Comments: This command allows the user to see the actual Rigid Body data according to Newton. This is helpful for debuggin purposes, as you can confirm where exactly each rigid body is in the scene. It's also helpful for debugging ragdolls and vehicles, as it allows you to visualize the actual bone / wheel data. This command uses 2D lines to draw the polygons that make up the rigid bodies. Newton supports multi-sided faces (quads, etc), which DBPro doesn't support. The other debug command, NDB_DebugMakeNewtonObject has to turn all faces into triangles, which means it's not as accurate as this 2D version. the trade-off is that this version has no backface culling, and is slower than the model version.

NDB_DebugMakeNewtonObject
syntax: obj = NDB_DebugMakeNewtonObject(flag)
flag Flag (int)

returns: Nothing.

Comments: This command allows the user to see the actual Rigid Body data according to Newton. This is helpful for debuggin purposes, as you can confirm where exactly each rigid body is in the scene. It's also helpful for debugging ragdolls and vehicles, as it allows you to visualize the actual bone / wheel data. This command creates a new object, with all of the rigid bodies in the entire Newton world. It is basically a "snapshot in time" of the Newton system at the given moment. The object defaults to wireframe drawing mode. In order to watch the Newton world in realtime, you must delete this object, and generate a new one for each frame. Alternatively, you can save each object, and then later go back and examine the various time steps very closely. This method is much faster than the NDB_DebugDrawNewtonLines method, but is not as accurate, because it turns 4+ sided faces into triangles (for DBPro rendering). .

A flag of "1" can be added, this makes the function only draw bodies with mass > 0, you can use this to ignore TreeCollision/other backgrond objects, and just check your active objects, which makes rendering faster.

NDB_DebugRigidBodyCount
syntax: int = NDB_DebugRigidBodyCount()

returns: integer value of number of rigid bodies in world.

Comments: This is a general debug function that returns the total number of Rigid Bodies in the Newton world. This method is not particularly optimized, and it intended for debug use only.