where \texttt{\textless path\_to\_library\_source\textgreater} must be replaced
by the path the path to the \texttt{reactphysics3d-0.4.0/} folder. It is the folder that
contains the \texttt{CMakeLists.txt} file. Running this command will launch the CMake command line interface.
Hit the 'c' key to configure the project. There, you can also change some predefined variables (see section \ref{sec:cmakevariables} for more details)
and then, hit the 'c' key again. Once you have set all the values as you like, you can hit the 'g' key to generate the makefiles in the build directory
The physics world will contain the bodies that you create and simulate them across time.
\subsection{Creating the Physics World}
\subsection{Customizing the Physics World}
\subsection{Updating the Physics World}
\subsection{Destroying the Physics World}
\section{Rigid Bodies}
\subsection{Creating a Rigid Body}
\subsection{Customizing a Rigid Body}
\subsection{Updating a Rigid Body}
\subsection{Destroying a Rigid Body}
\section{Collision Shapes}
When you create a rigid body, you need to specify a collision shape. This shape will be used to test collision between the body and its environment.
This section describes all the collision shapes available in the ReactPhysics3D library and how to use them. \\
Every collision shapes use a \emph{collision margin} which is a small distance around the shape that is used internally in the collision detection.
Some collision shapes have their collision margin integrated into the shape that you define and therefore you do not have to worry about it.
However, for some collision shapes, the collision margin is added around the shape that you define and therefore, you might have to compensate
for this small margin with the way you render the object. \\
Once you have created a collision shape object, you need to used it when you create a rigid body in the physics world using the
\texttt{DynamicsWorld::createRigidBody()} method. Note that during the rigid body creating, the collision shape object that you gave as a parameter
will be copied internally. Therefore, you can destroy the collision shape object right after the rigid body creation.
\subsection{Box Shape}
\begin{figure}[h]
\centering
\includegraphics{boxshape.png}
\label{fig:boxshape}
\end{figure}
The class \texttt{BoxShape} class describes a box collision shape centered at the origin of the body local space. The box is aligned with the local x, y and z axis.
In order to create a box shape, you only need to specify the three half extents dimensions of the box in the three X, Y and Z directions. \\
For instance, if you want to create a box shape with dimensions of 4 meters, 6 meters and 10 meters along the X, Y and Z axis respectively, you need to use the following code : \\
\begin{lstlisting}
// Half extents of the box in the x, y and z directions
const rp3d::Vector3 halfExtents(2.0, 3.0, 5.0);
// Create the box shape
const rp3d::BoxShape boxShape(halfExtents);
\end{lstlisting}
\vspace{0.6cm}
The \texttt{BoxShape} has a collision margin that is added to the box dimension you define. Therefore, the actual box shape will be a little bit larger that the one you define.
It is recommended that you use the default margin. In case, you really need to change the collision margin of your box shape (if the dimension of your box is small compared
to the default collision margin for instance), you can pass the length of the new collision margin (in meters) as a second parameter of the BoxShape constructor. \\
For instance, if you want to use a collision margin of 1 centimeter for your box shape, you can do it like this : \\
\begin{lstlisting}
// Create the box shape with a custom collision margin
const rp3d::BoxShape boxShape(halfExtents, 0.01);
\end{lstlisting}
\subsection{Sphere Shape}
\begin{figure}[h]
\centering
\includegraphics{sphereshape.png}
\label{fig:sphereshape}
\end{figure}
The \texttt{SphereShape} class describes a sphere collision shape centered at the origin of the body local space. You only need to specify the radius of sphere to create it. \\
For instance, if you want to create a sphere shape with a radius of 2 meters, you need to use the following code : \\
\begin{lstlisting}
// Create the sphere shape with a radius of 2m
const rp3d::SphereShape sphereShape(2.0);
\end{lstlisting}
\vspace{0.6cm}
The collision margin of the \texttt{SphereShape} is integrated into the sphere you define. Therefore, you do not need to worry about it and you cannot change it.
\subsection{Cone Shape}
\begin{figure}[h]
\centering
\includegraphics{coneshape.png}
\label{fig:coneshape}
\end{figure}
The \texttt{ConeShape} class describes a cone collision shape centered at the origin of the body local-space. The cone is aligned along the Y axis.
In order to create a cone shape, you need to give the radius of the base of the cone and the height of the cone (along the Y axis). \\
For instance, if you want to create a cone shape with a radius of 1 meter and the height of 3 meters, you need to use the following code : \\
\begin{lstlisting}
// Create the cone shape
const rp3d::ConeShape coneShape(1.0, 3.0);
\end{lstlisting}
\vspace{0.6cm}
The \texttt{ConeShape} has a collision margin that is added to the cone dimension that you define. Therefore, the actual cone shape will be a little bit larger that the one you define.
It is recommended that you use the default margin. In case, you really need to change the collision margin of your cone shape (if the dimension of your cone is small compared
to the default collision margin for instance), you can pass the length of the new collision margin (in meters) as a third parameter of the \texttt{ConeShape} constructor. \\
For instance, if you want to use a collision margin of 1 centimeter for your cone shape, you can do it like this : \\
\begin{lstlisting}
// Create the cone shape with a custom collision margin
const rp3d::ConeShape coneShape(1.0, 3.0, 0.01);
\end{lstlisting}
\subsection{Cylinder Shape}
\begin{figure}[h]
\centering
\includegraphics{cylindershape.png}
\label{fig:cylindershape}
\end{figure}
The \texttt{CylinderShape} class describes a cylinder collision shape centered at the origin of the body local-space. The cylinder is aligned along the Y axis.
In order to create a cylinder shape, you need to specify the radius of the base and the height of the cylinder (along the Y axis). \\
For instance, if you want to create a cylinder shape with a radius of 1 meter and the height of 3 meters, you need to use the following code : \\
\begin{lstlisting}
// Create the cylinder shape
const rp3d::Cylinder cylinderShape(1.0, 3.0);
\end{lstlisting}
\vspace{0.6cm}
The \texttt{CylinderShape} has a collision margin that is added to the cylinder dimension that you define. Therefore, the actual cylinder shape will be a little bit larger that the one you define.
It is recommended that you use the default margin. In case, you really need to change the collision margin of your cylinder shape (if the dimension of your cylinder is small compared
to the default collision margin for instance), you can pass the length of the new collision margin (in meters) as a third parameter of the \texttt{CylinderShape} constructor. \\
For instance, if you want to use a collision margin of 1 centimeter for your cylinder shape, you can do it like this : \\
\begin{lstlisting}
// Create the cylinder shape with a custom collision margin
The \texttt{CapsuleShape} class describes a capsule collision shape around the Y axis and centered at the origin of the body local space. It is the convex hull of two
spheres. It can also be seen as an elongated sphere. In order to create it, you only need to specify the radius of the two spheres and the height of the
capsule (distance between the centers of the two spheres). \\
For instance, if you want to create a capsule shape with a radius of 1 meter and the height of 2 meters, you need to use the following code : \\
\begin{lstlisting}
// Create the capsule shape
const rp3d::CapsuleShape capsuleShape(1.0, 2.0);
\end{lstlisting}
\vspace{0.6cm}
As for the \texttt{SphereShape}, the collision margin of the \texttt{CapsuleShape} is integrated into the capsule you define.
Therefore, you do not need to worry about it and you cannot change it.
\subsection{Convex Mesh Shape}
\begin{figure}[h]
\centering
\includegraphics{convexshape.png}
\label{fig:convexshape}
\end{figure}
The class \texttt{ConvexMeshShape} can be used to describe the shape of a convex mesh. In order to create a convex mesh shape, you need to supply the array with the coordinates of
the vertices of the mesh. The array is supposed to start with the three X, Y and Z coordinates of the first vertex, then the X, Y and Z coordinates of the second vertex and so on.
The first parameter of the \texttt{ConvexMeshShape} constructor is a pointer to the array of vertices coordinates, the second parameter is the number of vertices in the array and
the third parameter is the size (in bytes) of the data needed for a single vertex in the array (data used by all the three coordinates of a single vertex).
You need to make sure that the mesh you provide is indeed convex and also that the its origin of its local-space is inside the mesh. \\
The collision detection test with a convex mesh shape runs in $O(n)$ where $n$ is the number of vertices in the mesh. Collision detection can become expensive if there are
too many vertices in the mesh. It is possible to speed up the collision detection by providing information about the edges of the convex mesh. If you provide edges information
about the convex mesh, the collision detection will run in almost constant time at the cost of a little extra memory to store the edges information. In order to provide the edges
information, you need to call the \texttt{ConvexMeshShape::addEdge()} method for each edge of the mesh. The first parameter is the index of the first vertex of the edge and the
second parameter is the index of the second vertex. Do not worry about calling this method multiple times for the same edge, the edge information will be added only
once. \\
For instance, the following code adds the edges information into a convex mesh shape : \\
\begin{lstlisting}
// Add the edges information of the mesh into the shape
for (unsigned int i=0; i<mesh.getNbFaces(); i++) {
// Get the three vertex IDs of the vertices of the face
unsigned int v1 = getVertexIndexInFace(i, 0);
unsigned int v2 = getVertexIndexInFace(i, 1);
unsigned int v3 = getVertexIndexInFace(i, 2);
// Add the three edges into the collision shape
convexShape.addEdge(v1, v2);
convexShape.addEdge(v1, v3);
convexShape.addEdge(v2, v3);
}
\end{lstlisting}
\vspace{0.6cm}
Do not forget to enable the fast collision detection by asking the collision shape to use the edges information you have just provided. To do this, you need to
call the \texttt{ConvexMeshShape::setIsEdgesInformation()} method as in the following example : \\
\begin{lstlisting}
// Enable the fast collision detection
// using the edges information
collisionShape.setIsEdgesInformationUsed(true);
\end{lstlisting}
\subsection{Inertia Tensor of a Collision Shape}
When you create a rigid body, you need to specify its inertia tensor. The inertia tensor is a $3\times3$ matrix decribing how the mass is distributed inside the rigid body and this
will be used to calculate the rotation of the body. The inertia tensor depends on the mass and the shape of the body. \\
You can use the collision shape of a rigid body to compute its inertia tensor. To do that, you need to use the \texttt{CollisionShape::computeLocalInertiaTensor()} method of your collision
shape. This method takes two parameters. The first one if the inertia tensor matrix that need to be computed and the second one is the mass of the rigid body (in kilograms). For instance,
if you want to compute the inertia tensor matrix of a capsule shape with a mass of 3 kilograms, here is what the code looks like : \\
Joints are used to constraint the motion of the rigid bodies between each other. A single joint represents a constraint between two rigid bodies.
When the motion of the first body of the joint is known, the relative motion of the second body has at most six degrees of freedom (three for the
translation and three for the rotation). The different joints can reduce the number of degrees of freedom between two rigid bodies. \\
Some joints have limits to control the range of motion and some joints have motors to automatically move the the bodies of the joint at a given speed. \\
\subsection{Ball and Socket Joint}
The \texttt{BallAndSocketJoint} class describes a ball and socket joint between two bodies. In a ball and socket joint, the two bodies cannot translate with respect to each other.
However, they can rotate freely around a common anchor point. This joint has three degrees of freedom. This joint can be used to simulate a chain of bodies for instance. \\
In order to create a ball and socket joint, you first need to create an object of the \texttt{BallAndSocketJointInfo} class with the necessary information. You need to provide the pointers to the
two rigid bodies and also the coordinates of the anchor point (in world-space). At the joint creation, the world-space anchor point will be converted into the local-space of the two rigid
bodies and then, the joint will make sure that the two local-space anchor points match in world-space. Therefore, the two bodies need to be in a correct position at the joint creation. \\
Here is the code to create the \texttt{BallAndSocketJointInfo} object : \\
The class \texttt{HingeJoint} describes a hinge joint (or revolute joint) between two rigid bodies. The hinge joint only allows rotation around an anchor point and
around a single axis (the hinge axis). This joint can be used to simulate doors or pendulums for instance. \\
In order to create a hinge joint, you first need to create a \texttt{HingeJointInfo} object with the necessary information. You need to provide the pointers to the
two rigid bodies, the coordinates of the anchor point (in world-space) and also the hinge rotation axis (in world-space). The two bodies need to be in a correct position
when the joint is created. \\
Here is the code to create the \texttt{HingeJointInfo} object : \\
With the hinge joint, you can constraint the motion range using limits. The limits of the hinge joint are the minimum and maximum angle of rotation allowed with respect to the initial
angle between the bodies when the joint is created. The limits are disabled by default. If you want to use the limits, you first need to enable them by setting the
\texttt{isLimitEnabled} variable of the \texttt{HingeJointInfo} object to \emph{true} before you create the joint. You also have to specify the minimum and maximum limit
angles (in radians) using the \texttt{minAngleLimit} and \texttt{maxAngleLimit} variables of the joint info object. Note that the minimum limit angle must be in the
range $[-2\pi; 0]$ and the maximum limit angle must be in the range $[0; 2\pi]$. \\
For instance, here is the way to use the limits for a hinge joint when the joint is created : \\
You can also use the \texttt{HingeJoint::enableLimit()}, \texttt{HingeJoint::setMinAngleLimit()} and \texttt{HingeJoint::setMaxAngleLimit()} to specify the limits of the joint after its
creation. See the API documentation for more information.
\subsubsection{Motor}
A motor is also available for the hinge joint. It can be used rotate the bodies around the hinge axis at a given angular speed and such that the torque applied to
rotate the bodies does not exceed the maximum allowed torque. The motor is disabled by default. If you want to use it, you first have to activate it using the
\texttt{isMotorEnabled} boolean variable of the \texttt{HingeJointInfo} object before you create the joint. Then, you need to specify the angular motor speed (in radians/seconds)
using the \texttt{motorSpeed} variable and also the maximum allowed torque (in Newton $\cdot$ meters) with the \texttt{maxMotorTorque} variable. \\
For instance, here is how to enable the motor of the hinge joint when the joint is created : \\
You can also use the \texttt{HingeJoint::enableMotor()}, \texttt{HingeJoint::setMotorSpeed()} and \texttt{HingeJoint::setMaxMotorTorque()} to enabled the motor of the joint after its
creation. See the API documentation for more information.
\subsection{Slider Joint}
\subsection{Fixed Joint}
\subsection{Collision between the bodies of a Joint}
By default the two bodies involved in a joint are able to collide with each other. However, it is possible to disable the collision between the two bodies that are part
of the joint. To do it, you simply need to set the variable \texttt{isCollisionEnabled} of the joint info object to \emph{false} when you create the joint. \\
For instance, when you create a \texttt{HingeJointInfo} object in order to construct a hinge joint, you can disable collision between the two bodies of the joint as in the
