Newton SDK DBPro Wrapper v1.53

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

Convex Collision Primitives Interface Commands

NDB_NewtonCreateNull

syntax: int = NDB_NewtonCreateNull()

no variables passed to this function.

returns: integer index to the collision data created.

Comments: Makes a null collision object. Null objects will never colide with anything, but exist for special cases when you need a "space filler".

col = NDB_NewtonCreateNull() make null collision data, and store the index to it in the variable "col"

NDB_NewtonCreateSphere

syntax: int = NDB_NewtonCreateSphere( rad [ ,matrix_flag ] )

	radius	radius of the sphere (float)
	matrix_flag	flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments:Newton rigid bodies are made from collision data. The simplest way to make collision data is to use the built-in primitives. If you want the collision data offset from the origin of the body, set the data into the temp matrix, and then add a ",1" flag to the command. No flag assumes the collision data will be centered at the origin of the body.

col = NDB_NewtonCreateSphere( 2.0 ) make collision data of a sphere with radius 2.0, and store the index to it in the variable "col"

NDB_NewtonCreateBox

syntax: col = NDB_NewtonCreateBox( [x, y, z, matrix_flag] )

x X size of the box (float) *optional

y Y size of the box (float) *optional

z Z size of the box (float) *optional

matrix_flag flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments: Makes collision data of a simple box. If you don't supply the x,y,z values, the wrapper automatically uses the contents of temp vector 1. If you want the collision data offset from the origin of the body, set the data into the temp matrix, and then add a ",1" flag to the command. No flag assumes the collision data will be centered at the origin of the body.

col = NDB_NewtonCreateBox( 10.0, 2.0, 2.0 ) create collision data of a box with dimensions x=10 y=2 z=2 centered on the origin.
col = NDB_NewtonCreateBox( 1 ) create collision data of a box with dimensions stored in temp vector 1, and offset based on contents of temp matrix.

NDB_NewtonCreateCylinder

syntax: int = NDB_NewtonCreateCylinder( rad, height [ ,matrix_flag ] )

	rad	radius of the cylinder (float)
	height	height of the cylinder (float)
	matrix_flag	flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments:Makes a primitive cylinder object. Cylinders are by default aligned with the height along the x-axis. Call this function with a flag of ",1" to apply an offset matrix to the collision data.

col = NDB_NewtonCreateCylinder( 2.0, 5.0 ) make collision data of a cylinder with radius 2.0 height 5.0, and store the index to it in the variable "col"

NDB_NewtonCreateChamferCylinder

syntax: int = NDB_NewtonCreateChamferCylinder( rad, height [ ,matrix_flag ] )

	rad	radius of the cylinder (float)
	height	height of the cylinder (float)
	matrix_flag	flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments:Makes a primitive chamfer cylinder object. Chamfer Cylinders are by default aligned with the height along the x-axis. Call this function with a flag of ",1" to apply an offset matrix to the collision data.

col = NDB_NewtonCreateChamferCylinder( 2.0, 5.0 ) make collision data of a chamfer cylinder with radius 2.0 height 5.0, and store the index to it in the variable "col"

NDB_NewtonCreateCapsule

syntax: int = NDB_NewtonCreateCapsule( rad, height [ ,matrix_flag ] )

	rad	radius of the capsule (float)
	height	height of the capsule (float)
	matrix_flag	flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments:Makes a primitive capsule object. Capsules are by default aligned with the height along the x-axis. Call this function with a flag of ",1" to apply an offset matrix to the collision data.

col = NDB_NewtonCreateCapsule( 2.0, 5.0 ) make collision data of a capsule with radius 2.0 height 5.0, and store the index to it in the variable "col"

NDB_NewtonCreateCone

syntax: int = NDB_NewtonCreateCone( rad, height [ ,matrix_flag ] )

	rad	radius of the cone (float)
	height	height of the cone (float)
	matrix_flag	flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments:Makes a primitive cone object. Cones are by default aligned with the height along the x-axis. Call this function with a flag of ",1" to apply an offset matrix to the collision data.

col = NDB_NewtonCreateCone(12.0, 3.0 ) make collision data of a capsule with radius 12.0 height 3.0, and store the index to it in the variable "col"

NDB_NewtonCreateConvexHull

syntax: int = NDB_NewtonCreateConvexHull( obj_num [ ,matrix_flag ] )

	obj_num	object to use for convex hull data (integer)
	matrix_flag	flag whether or not to use offset matrix. 1 = use matrix *optional

returns: integer index to the collision data created.

Comments: Makes a convex hull primitive. Convex Hulls take a set of vertices, and "wrap" it, making the smallest possible convex shape that includes all of the vertices. Imagine wrapping an odd-shaped item in wrapping paper, and that's basically what it does. This command uses all of the vertices in the supplied object to create the collision.

load object "boulder.x", 10
col = NDB_NewtonCreateConvexHull( 10 ) make collision data from vertice data of object 10, and store the index to it in the variable "col"

NDB_NewtonCreateCompoundCollision

syntax: col = NDB_NewtonCreateCompoundCollision

no variables passed to this function.

returns: integer index to the collision data created.

Comments: Compound Collision is collision data based on several collision primitives. For example using 4 box primitives to represent a picture frame.
CAUTION you MUST follow the following step to make compound collion data:
call the function NDB_StartCompoundCollision.
Then, for each primitive:

make the primitive in the usual manner with an offset matrix.
call the function NDB_AddCollisionToArray to add the collision to the list.

call the NDB_NewtonCreateCompoundCollision function to get a reference to the compound collision.
Make your rigid body as normal with the NDB_NewtonCreateBody command.

NDB_StartCompoundCollision

syntax: NDB_StartCompoundCollision

no variables passed to this function

returns: nothing.

Comments: This command clears the wrapper's internal array of Newton Collision objects, for creating CompoundCollision objects. you must call this command before starting a new compound collision object. To add collisions to the array, use the NDB_AddCollisionToArray command. .

NDB_AddCollisionToArray

syntax: NDB_AddCollisionToArray col

col

index of collision data to add (integer)

returns: nothing.

Comments: This command adds the supplied Newton Collision data into the next slot in the collision array, for creating CompoundCollision objects. After adding all collision objects to the array, call the NDB_NewtonCreateCompoundCollision. Before adding the first collision to the array, make sure you call the NDB_StartCollisionArray command.

NDB_NewtonCreateTreeCollision

syntax: col = NDB_NewtonCreateTreeCollision( [db_num, limb flag] )

db_num dbpro object number of the object to turn into collision data.

flag optional method flag. 1 = limb-by-limb method for high poly objects.

returns: integer index to the collision data created.

Comments: Newton supports mesh-based collision. However objects made from mesh collision automatically have infinite mass, making them immobile. These objects are good for backgrounds, terrains, buildings, etc.

WAYS TO USE THIS COMMAND:

with existing dbpro object:
Call this command with the object number, and a tree collision will be made from that object's polygon data. For very high-poly objects (like advanced terrain objects, etc), this command may fail. In that case, add flag of "1" to specify a limb-by-limb method, which should work for most high-poly objects.

for other data:
Call this command with NO variables to start a manual Tree Collision object. Then use the NDB_NewtonTreeCollisionBeginBuild, NDB_NewtonTreeCollisionAddFace, NDB_NewtonTreeCollisionEndBuild commands to add polygon data to the Tree Collision.

NOTE when calling with a dbpro object, this command uses DBPro memblock and mesh commands internally. If you don't have any memblock or mesh commands in your program, DBPRO will NOT include the dll's for these commands in your final program exe. This will cause the program to crash when it tries to make the Tree Collision. The solution to this problem, is to put a few commands down at the botton of your progam (or somewhere they will never actually be called) to FORCE dbpro to include the memblock and mesh command dlls. You might use something like this:

if memblock exist(1) then end
if mesh exist(1) then end
...down at the bottom of your program.

load object "terrain.x", 100 load an object like normal.
col = NDB_NewtonCreateTreeCollision( 100 ) make collision data based on this object's polygon data.

NDB_NewtonCreateTreeCollisionUnOptimized

syntax: col = NDB_NewtonCreateTreeCollisionUnOptimized( [db_num, limb flag] )

db_num dbpro object number of the object to turn into collision data.

flag optional method flag. 1 = limb-by-limb method for high poly objects.

returns: integer index to the collision data created.

Comments: Same as above but no Optimization.

NDB_NewtonTreeCollisionBeginBuild

syntax: NDB_NewtonTreeCollisionBeginBuild col

col

collision data index returned in NDB_NewtonCreateTreeCollision command.

returns: nothing.

Comments: This command tells Newton you are about to add faces (polygon data) to an empty Tree Collision object. To use this manual method you must have created an empty TreeCollision object by calling NDB_NewtonCreateTreeCollision with no parameters.

NDB_NewtonTreeCollisionAddFace

syntax: NDB_NewtonTreeCollisionAddFace col

	col	collision data index returned in NDB_NewtonCreateTreeCollision command.
	(temp vector)	temp vectors used for passing values (vectors 1-3)

returns: nothing.

Comments: This command adds a face to the Tree Collision object. Before calling this command, you must place the local location of the 3 vertices that make up the polygon into temp vectors 1-3. You must have called NDB_NewtonTreeCollisionBeginBuild before calling this command.

NDB_NewtonTreeCollisionEndBuild

syntax: NDB_NewtonTreeCollisionEndBuild col, flag

	col	collision data index returned in NDB_NewtonCreateTreeCollision command.
	flag	optimization flag. 0 = off, 1 = on

returns: nothing.

Comments: This command completes a TreeCollision object, making it ready to be used by the NDB_NewtonCreateBody command. a flag of "1" tells Newton to optimize the collision data for more efficient behavior. This is highly recommended, as optimized objects run much faster.

NDB_NewtonCreateTreeCollisionFromSerialization

syntax: col = NDB_NewtonCreateTreeCollisionFromSerialization( filename )

filename

file containing serialized TreeCollision data (string)

returns: integer index to the collision data created.

Comments: This command allows the user to load previously saved TreeCollision data, instead of creating it from object geometry. This is MUCH faster than building tree collision data live.

col = NDB_NewtonCreateTreeCollisionFromSerialization( "serial.dat" )

NDB_NewtonTreeCollisionSerialize

syntax: NDB_NewtonTreeCollisionSerialize col, filename

	col	index to previously created collision data (integer)
	filename	file containing serialized TreeCollision data (string)

returns: nothing

Comments: This command saves a previously built TreeCollision into a compiled data file, which can then be loaded at runtim with the NDB_NewtonCreateTreeCollisionFromSerialization command above..

NDB_NewtonCreateTreeCollisionFromSerialization col, "serial.dat"

NDB_NewtonReleaseCollision

syntax: NDB_NewtonReleaseCollision col

col

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

returns: nothing.

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

NDB_NewtonCreateConvexHullWithScale

syntax: NDB_NewtonCreateConvexHullWithScale(db_obj)

	Temp Vec 1	Scalar for the convex hull.
	db_obj	object to use for convex hull data (integer)

returns: nothing.

Comments: Uses temp vector 1 as a scalar for the convex hull. use if you're scaling your DBPro objects after loading.

NDB_NewtonCreateTreeCollisionWithScale

syntax: NDB_NewtonCreateTreeCollisionWithScale( [db_num, limb flag] )

	Temp Vec 1	Scalar for the TreeCollision.
	db_num	Dbpro object number of the object to turn into collision data.
	flag	Optional method flag. 1 = limb-by-limb method for high poly objects.

returns: nothing.

Comments: Uses temp vector 1 as a scalar for the TreeCollision. use if you're scaling DBPro objects after loading.

NDB_NewtonCreateTreeCollisionWithScaleUnoptimized

syntax: NDB_NewtonCreateTreeCollisionWithScaleUnoptimized( [db_num, limb flag] )

	Temp Vec 1	Scalar for the TreeCollision.
	db_num	Dbpro object number of the object to turn into collision data.
	flag	Optional method flag. 1 = limb-by-limb method for high poly objects.

returns: nothing.

Comments: Same as above, but no optimization.

NDB_NewtonCreateConvexHullModifier

syntax: NDB_NewtonCreateConvexHullModifier( col )

col

Collision data index.

returns: nothing.

Comments: Makes a copy of an existing collision, which can then be scaled in realtime using the commands below. (NDB_NewtonConvexHullModifierSetMatrix and NDB_BuildScaleMatrix)

NDB_NewtonConvexHullModifierSetMatrix

syntax: NDB_NewtonConvexHullModifierSetMatrix( col )

col

Collision data index.

returns: nothing.

Comments: Sets the scale matrix for the modifier. Use the new NDB_BuildScaleMatrix command to build the actual matrix.

NDB_NewtonConvexHullModifierGetMatrix

syntax: NDB_NewtonConvexHullModifierGetMatrix( col )

col

Collision data index.

returns: nothing.

Comments: Fills temp matrix with the current scale matrix for the collision.

NDB_BuildScaleMatrix

syntax: NDB_BuildScaleMatrix sx, sy, sz

sx,sy,sz

Scale matrix values (float).

returns: nothing.

Comments: Builds a simple scale matrix, for use with the above commands.

NDB_NewtonConvexCollisionCalculateInertialMatrix

syntax: NDB_NewtonConvexCollisionCalculateInertialMatrix col

	col	index of collision data to calculate IM
	(vector 1)	principal inertia
	(vector 2)	center of mass

returns: nothing.

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

Comments:
Fills temp vector 1 with the values of the principal inertia for this collision.
Fills temp vector 2 with the values of the center of mass for this collision.

NDB_NewtonConvexCollisionCalculateVolume

syntax: vol = NDB_NewtonConvexCollisionCalculateVolume( col )

col

index of collision data to calculate volume

returns: collision geometry volume (float). This function will return zero if the body collision geometry is not 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. 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.