# 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

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