Newton Dynamics Engine Documentation Release 3 Oliver Nagy Sep 18, 2016 Contents 1 Installation 3 1.1 Linux...................................................3 1.2 Other Systems..............................................4 1.3 Questions/Problems...........................................4 2 Tutorials 5 2.1 Compiling And Linking A Trivial Program That Uses Newton.....................5 2.2 Basic Rigid Bodies And Forces.....................................6 2.3 Attach Custom Data To A Newton Body................................8 2.4 Ball Bouncing Off Surface........................................9 3 API Documentation 13 3.1 Misc................................................... 13 3.2 World................................................... 13 3.3 GroupID................................................. 24 3.4 MaterialSetup.............................................. 24 3.5 ContactBehaviour............................................ 28 3.6 CshapesConvexSimple.......................................... 32 3.7 CshapesConvexComplex......................................... 40 3.8 CollisionLibraryGeneric......................................... 46 3.9 TransUtil................................................. 52 3.10 RigidBodyInterface........................................... 53 3.11 ConstraintBall.............................................. 68 3.12 JointHinge................................................ 70 3.13 JointSlider................................................ 70 3.14 JointCorkscrew.............................................. 72 3.15 JointUniversal.............................................. 74 3.16 JointUpVector.............................................. 76 3.17 JointUser................................................. 77 3.18 JointCommon.............................................. 80 3.19 SpecialEffectMesh............................................ 83 3.20 Unclassified............................................... 88 3.21 Doxygen................................................. 88 4 Indices and tables 89 i ii Newton Dynamics Engine Documentation, Release 3 The Newton Dynamics engine is a physics engine to simulate life-like physics. More information about its used are available on its homepage. The source code is available on Github. Contents: Contents 1 Newton Dynamics Engine Documentation, Release 3 2 Contents CHAPTER 1 Installation You can build Newton with- or without graphical demos. For the core library (ie no graphical demos) you only need a C++ compiler, CMake, a Git client, and the TinyXML library. The sections below outline the process for the both options. 1.1 Linux This section assumes Ubuntu 16.04, but the procedure is similar for other Linux flavours. To prove it, here are the Dockerfiles for some of them: • Ubuntu 14.04 • Ubuntu 16.04 • Fedora 22 • Fedora 23 1.1.1 Core Library Only apt-get install build-essential cmake git libtinyxml-dev git clone https://github.com/MADEAPPS/newton-dynamics.git cd newton-dynamics mkdir build&& cd build cmake -DNEWTON_DEMOS_SANDBOX=OFF ..&& make 1.1.2 Library + Demos apt-get install build-essential cmake git libtinyxml-dev apt-get install libwxgtk3.0-dev libfreetype6-dev libopenal-dev libglew-dev git clone https://github.com/MADEAPPS/newton-dynamics.git cd newton-dynamics mkdir build&& cd build cmake -DNEWTON_DEMOS_SANDBOX=ON ..&& make The demos are all contained in a single executable. To start it from the build directory type: 3 Newton Dynamics Engine Documentation, Release 3 ../applications/demosSandbox/demosSandbox 1.2 Other Systems If you know how to compile and install Newton on any other system please submit a pull request. 1.3 Questions/Problems • Newton does not compile under latest Fedora 24 4 Chapter 1. Installation CHAPTER 2 Tutorials This “Starter Kit” is for people who have never used Newton before. The examples are self contained and strive to be as short as possible to demonstrate the feature. Consequently, the examples lack all bells and whistles, including error checks, automated Makefiles, or 3D graphics... you have been warned :) Note: The tutorials were developed on Kubuntu 16.04, but should run on all platforms supported by Newton. 2.1 Compiling And Linking A Trivial Program That Uses Newton Purpose: show how to compile a Newton simulation. The simulation creates a Newton world, steps it sixty times, and then destroys the world again. Literally nothing will happen since the world is empty. Here is the code: 1 #include <stdio.h> 2 #include "Newton.h" 3 4 5 int main( int argc, const char * argv[]) 6 { 7 // Print the library version. 8 printf("Hello, this is Newton version %d\n", NewtonWorldGetVersion()); 9 10 // Create the Newton world. 11 NewtonWorld* const world= NewtonCreate(); 12 13 // Step the (empty) world 60 times in increments of 1/60 second. 14 const float timestep= 1.0f/ 60; 15 for(int i=0; i<60; i++){ 16 NewtonUpdate(world, timestep); 17 } 18 19 // Clean up. 20 NewtonDestroyAllBodies(world); 21 NewtonDestroy(world); 22 23 return 0; 24 } 5 Newton Dynamics Engine Documentation, Release 3 2.1.1 Linux If you installed the Newton library into your system the you can compile, link, and run the program with these commands: 1 $ g++ tut0.cpp -o tut0 -lNewton -lpthread 2 $ ./tut0 If you did _not_ install the library and want to use the version from your source and build directory, then you need a longer command: 1 $ g++ tut0.cpp -o tut0 -I ../../coreLibrary_300/source/newton/ -L ../../build/lib/ - ,!lNewton -lpthread -Wl,"-rpath=../../build/lib/" 2 $ ./tut0 This may look intimidating but is straightforward. The -I ../../coreLibrary_300/source/newton/ flag tells the compiler where to find Newton.h. Similarly, -L ../../build/lib/ tells the linker where to look for additional libraries. The next flag (-lNewton) tells the linker to link our program against the libNewton.so library we built in Installation. Newton uses threads, thus we linke it to -lpthread. Finally, the purpose of -Wl,"-rpath=../../build/lib/" is to bake the location of the Newton library into the executable, or other- wise the runtime linker will probably not find it. 2.1.2 Other Please submit pull request for instructions. 2.2 Basic Rigid Bodies And Forces Purpose: create a spherical body, apply a force, and track its motion over time. We are now adding two more functions. The first, addSphereToSimulation creates a sphere in the Newton world and parameterises it (mass, inertia). It also installs the second new function cb_applyForce as a callback. Newton will trigger that callback whenever it moves the body. It will not trigger it if the body is already at rest. Inside the callback we query the state matrix and print the current position. Furthermore, we apply a force along the y axis, which makes the body accelerate in that direction. Since that force is 1N, and the simulation runs for one second, the body must move exactly 0.5 Meters. Here is the code: 1 #include <stdio.h> 2 #include "Newton.h" 3 4 5 void cb_applyForce(const NewtonBody* const body, dFloat timestep, int threadIndex) 6 { 7 // Apply a force to the object. 8 dFloat force[3]={0, 1.0,0}; 9 NewtonBodySetForce(body, force); 10 11 // Query the state (4x4 matrix) and extract the body's position. 12 float state[16]; 13 NewtonBodyGetMatrix(body, state); 14 printf("Time %.3fs: x=%.3f y=%.3f z=%.2f\n", 15 timestep, state[12], state[13], state[14]); 6 Chapter 2. Tutorials Newton Dynamics Engine Documentation, Release 3 16 } 17 18 19 void addSphereToSimulation(NewtonWorld *world) { 20 // fixme: what is this? 21 float foo[16]={ 22 1.0f, 0.0f, 0.0f, 0.0f, 23 0.0f, 1.0f, 0.0f, 0.0f, 24 0.0f, 0.0f, 1.0f, 0.0f, 25 0.0f, 0.0f, 0.0f, 1.0f 26 }; 27 28 // Create the sphere. Is this radius or diameter? 29 NewtonCollision* const collision= NewtonCreateSphere(world,1,0, NULL); 30 31 // fixme: what is this for? 32 NewtonBody* const body= NewtonCreateDynamicBody(world, collision, foo); 33 34 // fixme: has no doc string. Is this mass, I_xx, I_yy, and I_zz? 35 NewtonBodySetMassMatrix(body, 1.0f,1,1,1); 36 37 // Install callback. Newton will call it whenever the object moves. 38 NewtonBodySetForceAndTorqueCallback(body, cb_applyForce); 39 } 40 41 42 int main( int argc, const char * argv[]) 43 { 44 // Create the Newton world. 45 NewtonWorld* const world= NewtonCreate(); 46 47 // Add the sphere. 48 addSphereToSimulation(world); 49 50 // Step the (empty) world 60 times in increments of 1/60 second. 51 const float timestep= 1.0f/ 60; 52 for(int i=0; i<60; i++){ 53 NewtonUpdate(world, timestep); 54 } 55 56 // Clean up. 57 NewtonDestroyAllBodies(world); 58 NewtonDestroy(world); 59 60 return 0; 61 } 2.2.1 Linux To compile, link, and run the program type: 1 $ g++ tut1.cpp -o tut1 -I ../../coreLibrary_300/source/newton/ -L ../../build/lib/ - ,!lNewton -lpthread -Wl,"-rpath=../../build/lib/" 2 $ ./tut1 2.2. Basic Rigid Bodies And Forces 7 Newton Dynamics Engine Documentation, Release 3 2.2.2 Other Please submit pull request for instructions. 2.2.3 Questions/Problems • What is the third parameter to NewtonCreateDynamicBody? • What is shapeID? 2.3 Attach Custom Data To A Newton Body Newton provides NewtonBodySetUserData and NewtonBodySetUserData to set and retrieve custom user data, respectively. Their usage is straightforward as the next example illustrates. Here is the code: 1 #include <stdio.h> 2 #include "Newton.h" 3 4 5 // Define a custom data structure to store a body ID. 6 struct UserData { 7 int bodyID=0; 8 }; 9 10 11 void cb_applyForce(const NewtonBody* const body, dFloat timestep, int threadIndex) 12 { 13 // Request the custom data,