more work on the new Bullet manual/quickstart guide, and cross reference to HelloWorld.cpp source code

Demos/HelloWorld/HelloWorld.cpp

@@ -13,7 +13,7 @@ subject to the following restrictions:
 3. This notice may not be removed or altered from any source distribution.
 */
 
-
+///-----includes_start-----
 #include "btBulletDynamicsCommon.h"
 #include <stdio.h>
 
@@ -21,8 +21,10 @@ subject to the following restrictions:
 
 int main(int argc, char** argv)
 {
+	///-----includes_end-----
 
 	int i;
+	///-----initialization_start-----
 
 	///collision configuration contains default setup for memory, collision setup. Advanced users can create their own configuration.
 	btDefaultCollisionConfiguration* collisionConfiguration = new btDefaultCollisionConfiguration();
@@ -40,6 +42,8 @@ int main(int argc, char** argv)
 
 	dynamicsWorld->setGravity(btVector3(0,-10,0));
 
+	///-----initialization_end-----
+
 	///create a few basic rigid bodies
 	btCollisionShape* groundShape = new btBoxShape(btVector3(btScalar(50.),btScalar(50.),btScalar(50.)));
 
@@ -108,7 +112,7 @@ int main(int argc, char** argv)
 /// Do some simulation
 
 
-
+	///-----stepsimulation_start-----
 	for (i=0;i<100;i++)
 	{
 		dynamicsWorld->stepSimulation(1.f/60.f,10);
@@ -127,8 +131,11 @@ int main(int argc, char** argv)
 		}
 	}
 
+	///-----stepsimulation_end-----
 
 	//cleanup in the reverse order of creation/initialization
+	
+	///-----cleanup_start-----
 
 	//remove the rigidbodies from the dynamics world and delete them
 	for (i=dynamicsWorld->getNumCollisionObjects()-1; i>=0 ;i--)
@@ -168,5 +175,6 @@ int main(int argc, char** argv)
 	//next line is optional: it will be cleared by the destructor when the array goes out of scope
 	collisionShapes.clear();
 
+	///-----cleanup_end-----
 }
 

docs/bullet_manual.tex

@@ -3,18 +3,26 @@
 % http://bulletphysics.org
 % Written by Erwin Coumans
 
-% Preamble or the global definitions of the book/manual
-% Use openany to avoid empty page after TOC
-\documentclass[openany]{book}
+% Preamble (global definitions of the book/manual)
+% Use openany option for documentclass to avoid empty page after TOC
+
+%\documentclass[openany]{book}
+%scrbook is easier on the eyes, and use a bigger font
+\documentclass[openany,DIV=calc,16pt]{scrbook}
 
 % The english package can help breaking words
 \usepackage[english]{babel}
 
+%The Charter or Utopia font is easier on the eyes for screen
+\renewcommand{\familydefault}{bch}%Charter font
+%\renewcommand{\familydefault}{put} %Utopia font
+
+
 % Titlepic allows us to use a picture on the frontpage
 \usepackage{titlepic}
 \usepackage{graphicx}
 
-\usepackage[a4paper, top=3cm, bottom=3cm]{geometry}
+\usepackage[a4paper, left=2cm, right=1cm,  top=2cm, bottom=3.5cm]{geometry}
 \usepackage[latin1]{inputenc}
 
 % If using \doublespacing include the setspace package
@@ -22,38 +30,76 @@
 \usepackage{fancyhdr}
 \usepackage{tocloft}
 
+
 % The hyperref package already include package url
 \usepackage[colorlinks=true]{hyperref}
 % \setcounter{secnumdepth}{4}
 \usepackage{makeidx}\makeindex
 
+%support for C++ source code snippets
+%you can even import existing C++ code as-is
+%or a range of lines within markers beween rangeprefix/rangesuffix
+\usepackage{listings}
+\usepackage{color}
+\renewcommand{\lstlistingname}{Source Code}
+\renewcommand{\lstlistlistingname}{Source Code Listings}
+\lstset{
+	tabsize=2,	language=C++, keywordstyle=\color[rgb]{0,0,1},
+	 commentstyle=\color[rgb]{0.133,0.545,0.133},
+     stringstyle=\color[rgb]{0.627,0.126,0.941},
+      breaklines=true,
+     numberstyle=\tiny,
+	basicstyle=\ttfamily\tiny,
+	rangeprefix=///-----,	rangesuffix=-----,
+	includerangemarker=false,
+	numbers=left,	stepnumber=1,
+	frame=single,
+}
+
+
 % Set the tolerance so TeX really breaks the line
 % and don't run into the right margin (avoid overfull boxes)
-\tolerance=5000
+\tolerance=10000
+
+%end of preamble
 
 \begin{document}
 
 %	\pagestyle{fancy}
 
-	\pagenumbering{arabic}
-	\title{\textbf{Bullet 2.81 Physics SDK Manual}}
+%\pagenumbering{}
+%
+	\title{\textbf{Bullet 2.81 Quickstart Guide}}
 	\titlepic{\includegraphics[width=0.7\textwidth]{bullet_logo_2010_9.eps}}
+%
 	\author{Erwin Coumans}
 	\maketitle
 
+
 	\renewcommand{\cftchapdotsep}{\cftdotsep}
 	\tableofcontents
+	
+	
+	\pagenumbering{arabic}
 
 %	\fancyhf{}
 %	\doublespacing
 
 % include all the chapters as separate tex files
 % on Mac OSX it is really nice to use the Texpad application for automatic navigation
+
 	\include{intro}
+	\include{helloworld}
+	\include{faq}
+	
+	\clearpage
+	\addcontentsline{toc}{chapter}{Source code listings}
+	\lstlistoflistings
 
 	\clearpage
 	\addcontentsline{toc}{chapter}{Index}
 	\printindex
 
+	
 \end{document}
 

docs/faq.tex

@@ -0,0 +1,13 @@
+
+\chapter{Frequently asked questions}
+Here is a placeholder for a FAQ. For more information it is best to visit the Bullet Physics forums at \url{http://bulletphysics.org}.
+\section{Build problems}
+todo
+\section{Performance issues}
+todo
+\section{Physics issues}
+todo
+\section{Collision issues}
+todo
+\section{Ray testing}
+todo

docs/helloworld.tex

@@ -0,0 +1,15 @@
+\chapter{Hello World}
+\section{C++ console program}
+Let's discuss the creation of a basic Bullet simulation from the beginning to the end. For simplicity we print the state of the simulation to console using printf, instead of using 3D graphics to display the objects. The source code of this tutorial is located in \path{Demos/HelloWorld/HelloWorld.cpp}. 
+
+It is a good idea to try to compile, link and run this HelloWorld.cpp program first.
+
+As you can see in \ref{helloworld_includefiles} you can include a convenience header file \path{btBulletDynamicsCommon.h}.
+
+\lstinputlisting[caption=HelloWorld.cpp include header, label=helloworld_includefiles,linerange=includes_start-includes_end]{../Demos/HelloWorld/HelloWorld.cpp}
+Now we create the dynamics world:
+\lstinputlisting[caption=HelloWorld.cpp initialize world, label=stepsimulation,linerange=initialization_start-initialization_end]{../Demos/HelloWorld/HelloWorld.cpp}
+Once the world is created you can step the simulation as follows:
+\lstinputlisting[caption=HelloWorld.cpp step simulation, label=stepsimulation,linerange=stepsimulation_start-stepsimulation_end]{../Demos/HelloWorld/HelloWorld.cpp}
+At the end of the program you delete all objects in the reverse order of creation. Here is the cleanup listing of our HelloWorld.cpp program.
+\lstinputlisting[caption=HelloWorld.cpp cleanup, label=cleanup,linerange=cleanup_start-cleanup_end]{../Demos/HelloWorld/HelloWorld.cpp}

docs/intro.tex

@@ -26,9 +26,9 @@ Bullet Physics is a professional open source collision detection, rigid body and
 \subsection{New in Bullet 2.81}
 \begin{itemize}
 	\item SIMD and Neon optimizations for iOS and Mac OSX, thanks to a contribution from Apple
-	\item Rolling Friction using a constraint, thanks to Erin Catto for the idea. \\See \path{Demos/RollingFrictionDemo/RollingFrictionDemo.cpp}
-	\item XML serialization\\See \path{Bullet/Demos/BulletXmlImportDemo} and \path{Bullet/Demos/SerializeDemo}
-	\item Gear constraint\\See \path{Bullet/Demos/ConstraintDemo}.
+	\item Rolling Friction using a constraint, thanks to Erin Catto for the idea. See \path{Demos/RollingFrictionDemo/RollingFrictionDemo.cpp}
+	\item XML serialization. See \path{Bullet/Demos/BulletXmlImportDemo} and \path{Bullet/Demos/SerializeDemo}
+	\item Gear constraint. See \path{Bullet/Demos/ConstraintDemo}.
 	\item Improved continuous collision response, feeding speculative contacts to the constraint solver. See \path{Bullet/Demos/CcdPhysicsDemo}
 	\item Improved premake4 build system including support for Mac OSX, Linux and iOS
 	\item Refactoring of collision detection pipeline using stack allocation instead of modifying the collision object. This will allow better future multithreading optimizations.