This is a quick walk-through on how to develop a basic 3D Native Client app. You can try out my test app from the Chrome Web Store here or here.

Alternatively you can visit http://bulletphysics.org/nacl but in that case you need to enable Native Client by typing about://flags in the Chrome address bar. Chrome Web Store Native Client apps don’t require flags.

Either way, make sure your Chrome About Box shows version 15 or later.

Some features of the simple test app:

• OpenGL ES2 3D rendering with textures
• Mouse interaction
• Load binary files using a file chooser
• Use of middleware: Bullet Physics, libjpeg

Download the SDK

You can download the Native Client SDK and all tutorial and build system files in a single self-contained zip file here (64 MB). It should work out-of-the-box under Windows. This tutorial also builds under Linux or Mac OSX but that is left as an exercise for the reader (or leave a comment for help).

Setup your build system

Just unzip the zip file (64 MB) in a folder without spaces in the name and you are all set to go under Windows.

The Native Client SDK comes with a gcc-based compiler toolchain. You need to tell your build system the location of the C compiler (CC), C++ compiler (CXX) and linker (AR). Above zip file includes make.exe and Makefiles that work under Windows out-of-the-box. There is no need to install Cygwin or MinGW. I used premake to generate the Makefiles.

Add some salt and pepper

An API called Pepper is used to provide hooks between Native Client and web browser services such as HTML5 and 3D. This test application was a port from a simple Win32 application. I used the Tumbler NaCl example as a starting point. The original version is located in build\nacl\nacl_sdk\pepper_15\examples\tumbler. In order to ‘port’ it to Native Client in a web page, the following changes were made. Most of the source code is shared and portable, to make debugging easier.

• Program entry point: The Windows application used WinMain as a program entry point. For Native Client the entry point is the constructor of your module.
• All of the OpenGL ES initialization of matrices, shaders, textures, vertex and index buffers are the same, except for creating the context.
• Keyboard and mouse input. Instead of a Windows event you register for keyboard and/or mouse events and implement the event callback.
• Loading files from the local file system is not possible for obvious security reasons, so there is no ‘fopen’ command. You can let the user pick a file using the browsers build-in File Chooser, load the file in memory and use Javascript to pass the file to the Native Client module. Binary files can be base64 encoded by the browser, and decoded by your Native Client code. This works well in practice. In the future you can call the File Chooser directly from NaCl C++ code.

Build the executable

Click on build/nacl.bat and wait. Here is the content of the batch file:

set NACL_TARGET_PLATFORM=pepper_15
set NACL_SDK_ROOT=%CD%/nacl/nacl_sdk
 
premake4 --with-nacl gmake
cd nacl
 
set AR=%NACL_SDK_ROOT%\%NACL_TARGET_PLATFORM%\toolchain\win_x86_newlib\bin\x86_64-nacl-ar.exe
set CC=%NACL_SDK_ROOT%\%NACL_TARGET_PLATFORM%\toolchain\win_x86_newlib\bin\x86_64-nacl-gcc.exe
set CXX=%NACL_SDK_ROOT%\%NACL_TARGET_PLATFORM%\toolchain\win_x86_newlib\bin\x86_64-nacl-g++.exe
 
set config=release32
make
 
set config=release64
make

This builds two Native Client executables, 32bit x86 and 64bit x64, they are located in build\nacl\nginx-1.1.2\html\NativeClientTumbler.exe and build\nacl\nginx-1.1.2\html\NativeClientTumbler_64.exe
The web page know how to load this module using a manifest file called tumbler.nmf :

{
  "program": {
    "x86-64": {"url": "NativeClientTumbler_x64.exe"},
    "x86-32": {"url": "NativeClientTumbler.exe"}
  }
}

The index.html web page can load the Native Client code using this tumbler.nmf file. Check out index.html and tumbler.js for details.

Test the application

Click on build/nacl_runtest.bat and confirm that the nginx web browser is allowed to wait for connections.

Native Client applications hosted in the Chrome Web Store should run without special flags or settings. In order to run NaCl modules in web pages outside of the Store you need to enable Native Client manually. Just type about://flags in the Chrome address bar and enable the Native Client setting.

Now open Chrome and type http://localhost/index.html and if all goes well you can play your app.

Debug the application

You can use ‘printf’ debugging using the Javascript console, but in most cases it is easier to maintain a Windows version and perform debugging under Visual Studio. You can compile the tutorial under Visual Studio by clicking on the build/vs2008.bat file and open the GLES2_BulletBlendReader_Angle project. This project emulates OpenGL ES2 under Windows using a DirectX wrapper called Angle.

Deploy to the Chrome Web Store

You can make your C++ Native Client module available for free or for sale in the Chrome Web Store. A one-time registration fee of just 5$ is used, probably to stop spam. You have to create a manifold.json that provides the information about your application. This includes the name, description and where the web page and assets are located. Here is the manifest used for this tutorial:

{
    "name": "Bullet Physics NaCl Test",
    "version": "0.8",
    "description": "This Native Client module runs a C++ Bullet Physics simulation.",
    "app": {
	    "launch": {
	       "local_path": "index.html"
	    }
	  },
	  "icons": {
	  "16": "bullet_icon16.png",
      "128": "bullet_icon128.png"
    }
}

Notes

Most of the Google NaCl SDK relies on having Python installed, and I wanted this tutorial to work without external dependencies such as Python, Cygwin or MinGW etc. I used the following replacements:

• Python was used for the scons build system. I replaced scons by Makefiles, because I think Makefiles are more standard and simpler to adapt to other build systems. I used premake4 to generate the Makefiles to keep it self-contained.
• Python was also used to download and update the Native Client SDK. To avoid this, the zip file already contains the Native Client SDK and the build system knows its location. If you have Python installed you can still run this updater, it is located under build\nacl\nacl_sdk\update_naclsdk.bat in the zip file.
• Finally, Python was used for the web server. I replaced this with the tiny but powerful nginx web server.

I recommend checking out the links below if you are interested to learn more.

Enjoy!

Useful Links

http://gonacl.com (it has some links to other middleware that support Native Client such as FMOD, Ogre and Unity)

http://code.google.com/chrome/nativeclient

https://groups.google.com/group/native-client-discuss

http://code.google.com/chrome/webstore/articles/apps_vs_extensions.html

A typical destruction process can be divided in two parts:

1. the preparation of the 3D geometry, usually done during the creation of a game
2. the breaking of objects when playing the game

There are many different ways to prepare the 3D geometry for fracture. Often this involves 3D content creation tools such as Autodesk Maya, 3ds Max or the open source Blender 3D modeler.

Voronoi shatter

Cutting a 3D model into pieces using voronoi shatter is very popular. For example it is used by the Epic Unreal Engine. You first create particles inside the 3D model. Then you create Voronoi regions that enclose those points. Some good algorithms are developed to compute voronoi regions efficiently, given a closed mesh and enclosed points, for example Fortune’s algorithm.

Tetrahedralization

It is also possible to subdivide the original 3d model into a set of tetrahedra, this process is also called a tetrahedralization. It can be done using Delaunay Triangulation, which is the dual of voronoi regions. There are some open source libraries that can perform this task, such as Netgen, Tetgen and CGal for example. It is a complicated process, but there is also a much simpler approximation, explained in page 18 of the notes of the excellent real-time physics SIGGRAPH course.

Boolean operations

Boolean operations, also known as constructive solid geometry (CSG) is a way to perform volumetric operations between 3D models. For example you can add two volumes together, or compute the difference between two objects, or take the intersection. Those operations allow you to break original 3D models into smaller pieces, similar to a cookie cutter.

Cutting, slicing etc

Of course there are many other methods to generate a pre-fractured model, for example an artist can create the parts by hand, or some slicing algorithm can be applied based on polygon clipping.

As this is just a short overview, let’s move on to the runtime breaking methods. Aside from triggering a pre-recorded animation of a destruction sequence, some common approaches are:

Real-time booleans

The Red Faction games by Volition showed some cool destruction in their worlds. Their Geo Mod technology is based on the application of real-time boolean operations. Recently I encouraged Stan Melax to open source his real-time booleans demo, so you can check it out at http://melax.googlecode.com. Here is a screenshot:

The actual boolean operations are based on the merging of BSP trees, as described by Bruce Naylor, see the pdf here. Although the technique allows a lot of freedom to destroy the environment, it requires an additional physics system to analyse if buildings need to collapse.

Finite element method

The Finite Element Method (FEM) uses continuum mechanics to simulate deformation and fracture. There are several ways of implementing FEM, either using explicit integration or implicit integration. Recomputing the stiffness matrix every simulation frame can be very expensive, and stiffness warping avoids this by using a corotational mapping. Such corotational FEM method is used by Pixelux Digital Molecular Matter (DMM) in Lucas Arts Star Wars games, as described in this SIGGRAPH paper. I recently extracted an open source implementation from the Open Tissue physics library. You can grab the source code from my github repository it is in the dynamics/corotational_fem folder, here is a screenshot:

Some researchers in Inria, France, accelerated FEM on the GPU using CUDA, and it could simulate 47k tetrahedra at over 200 frames per second on a modern GPU. Their source code is hidden in a SVN repository of the Sofa framework ( svn checkout svn://scm.gforge.inria.fr/svn/sofa/branches/Sofa-1.0 )

Breakable composit rigid body

Some games use a plain rigid body dynamics engine for destruction, such as Angry Birds, which uses the open source Box2d engine. In many cases you want more control over the destruction effect.

Here are some steps that describe the composite rigid body fracture method. First we prepare the geometry into fractured pieces and now we need to ‘glue’ them together. We need to create some connections between those pieces. There are several ways to do this. One way is to define connections between every piece and every other piece. This gives the most control, but the performance can be slow due to the many connections. Another way to compute connections is to automatically compute them based on collision detection: compute the contact points between touching pieces, and only create connections when there is a contact point. Then you can create a breaking threshold for those connections.

Once we glued the pieces into a single rigid body, we can perform the runtime fracture. If there is a collision impact, we compute the impulse. If this impulse is larger than a chosen threshold, we propagate this impulse through the connections. Those connections can be weakened or broken.

After this, we need to determine the disconnected parts, we use the union find algorithm for this, and then create new rigid bodies for each separate part. Of course the inertia matrix needs to be updated properly. In our open source Bullet physics library there is a demo that shows how to implement this, it is under Bullet/Demos/BulletFractureDemo.

Breakable rigid body constraints

We can also simulate the object by using a rigid body for each fracture piece, and connect the pieces using breakable constraints.

For example this can be a fixed rigid body constraint that connects two pieces. You can see that the object is bending a little bit after the collision, because the constraints are not perfectly stiff. This bending effect can be desired in some cases, and this method has been used in some games and movies.

Hybrid and other methods

It is also possible to use a combination of different methods. For example you can use FEM to determine when and where to break and use rigid body simulation to simulate the broken pieces as described in this paper (pdf).

If you have any experience or thoughts of fracture and destruction in games, please reply!

This article is about setting up your Android development environment in combination with Visual Studio and WinDBG for mobile systems beta. The result is that you can create and debug Android projects from within Visual Studio on emulator and the actual device (that doesn’t need to rooted). Those project files are kept in sync with the original NDK build files (Android.mk etc) so they are compatible with the command-line tools. In other words, you can still use ndk-build and ant. If you are a happy Eclipse user, this posting isn’t for you.

There is an open source project called vs-android that integrates Android with Visual Studio, but it doesn’t support debugging as far as I know.

Before we can install WinGDB we need to have the NDK in working order. Google don’t provide a single installer for their NDK. Instead they ask developers to gather all information and installers from various websites. Many things can go wrong this way. On top of that, their 64bit NDK installer has a bug that doesn’t find the Java installation path until you hit “back/next”. Steps 1 to 6 below deals with installing the NDK.

If you already have a working recent NDK environment you can skip to step 7 for WinGDB.

1) Download the JDK from the Oracle website after accepting the agreement, the current version is jdk-6u26-windows-x64.exe

Install the JDK to C:\Program Files\Java\jdk1.6.0_26\ and install JRE to C:\Program Files\Java\jre6\ and make sure java.exe is in your path.

2) Download Apache Ant apache-ant-1.8.2-bin.zip from the http://ant.apache.org/ website and
unzip it to c:\android\apache-ant-1.8.2-bin\

3) Download Android SDK from http://developer.android.com/sdk/index.html, for example this recent installer installer_r12-windows.exe

Run the installer.
It might complain that the JDK is not found:

Just hit the Back button and Next:

Hit next and choose your destination path. I changed it from
C:\Program Files (x86)\Android\android-sdk to C:\Android\android-sdk to keep the SDKs together.

4) Start the SDK manager

Your choice of packages depends which Android versions you target for your App. You can just select the default set, it might take a while to download though.

5) Download the Android NDK android-ndk-r6-windows.zip and unzip it in c:\android.

6) Install Cygwin from http://cygwin.com/install.html using setup.exe

Install Cygwin to the default location, c:\cygwin and select a mirror

Make sure to select the ‘make’ tool by searching for ‘make’ and enabling ‘install’ for the ‘Devel’ packages:

7) Download WinGDB from http://www.wingdb.com/wgMobileEdition.htm, currently the beta version is WinGDB-2.0-b1006-mse.msi

8)Run the WinDBG installer

Then configure WinGDB using the WinGDB preferences tab in Visual Studio

and set the directories where you install/unzipped the packages in previous steps:

9) Create a new Android project in Visual Studio

and choose the name and target

Once the project is created, change some project properties

and change the debug target to device. You can also leave it to use the emulator, but I find it too sluggish.

10) Connect your Android device and make sure the USB drivers are installed. For my Asus TF101 the USB drivers were automatically installed

Enable USB debugging on your Android device, put some breakpoint in your main.cpp and hit F7 or F5 within Visual Studio and if all goes well:

If the connection doesn’t work, you could try disabling your firewall and/or anti-virus scanner. Another option is to enable the Pipe method instead of TCP/IP:

WinGDB also supports import of existing Android projects, but your mileage might vary. If it works for you (or not), please leave a comment.

Note that WinGDB mobile edition is still in beta, so please report problems to their support or forums. I ran into a few issues that hopefully get sorted in the final version of WinGDB, but I find the free beta already useful enough to try it out.

Previously I blogged here about convex collision detection using the separating axis test and Sutherland Hodgeman clipping. In a few upcoming blog postings I want to discuss how to perform the collision detection and simple particle/rigid body dynamics on the GPU for fun.

The result of rigid body dynamics is a world transform for each object: the position and orientation. The world position and the orientation (represented as a quaternion) can both be stored as a float4/Vector4 when we use 16-byte alignment.

We could render individual objects on the GPU by making calls to the OpenGL or Direct3D API from the CPU side, updating the world transform for each object and rendering them one by one.

If we run the particle or rigid body simulation on the GPU, this means that we have to transfer the world transform from GPU to main memory, making the calls on CPU, which transfers those same transforms back to GPU. There is a more efficient way to do this, and this is called OpenCL interop: sharing a single buffer between graphics API and OpenCL. DirectCompute and Direct3D has a similar feature, but in this article we use OpenCL and OpenGL.

Preparation:

1. Store all the transforms in a Vertex Buffer Object (VBO) on the GPU
2. A GLSL shader that renders instanced meshes using the transforms from this VBO
3. Initialize OpenCL

During the rendering of each frame:

1. call glFinish to make sure the GPU doesn’t access the VBO
2. Acquire the OpenGL VBO as an OpenCL buffer
3. Execute some OpenCL kernels that compute and update the transforms in this buffer
4. Release the OpenCL buffer back to OpenGL
5. Render all instances using a single call using glDrawElementsInstanced

I’ll briefly go over important bits in the C/C++ implementation for the OpenCL/GL interop, there is link at the end of this article where you can download all code.

Vertex Buffer Object

All instances share the same mesh data, a vertex buffer and index buffer, while each of them has its own transform. For this example I store all this data in a single VBO with a memory layout as follows:

The code to initialize this VBO is

glGenBuffers(1, &cube_vbo);
glBindBuffer(GL_ARRAY_BUFFER, cube_vbo);
char* dest=  (char*)glMapBuffer( GL_ARRAY_BUFFER,GL_WRITE_ONLY);
memcpy(dest,cube_vertices,sizeof(cube_vertices));
float* positions = (float*)(dest+sizeof(cube_vertices));
float* orientations = (float*)(dest+sizeof(cube_vertices) + POSITION_BUFFER_SIZE);
//initialize the positions/orientations
glUnmapBuffer( GL_ARRAY_BUFFER);

GLSL vertex shader

For the GLSL vertex shader we need to apply the world transform, position and quaternion. As we use a single VBO and the positions and orientations are stored after the vertices, we need to specify the memory layout so the shader know where to find the position/orientation. For OpenGL this offset can be passed on using glVertexAttribPointer and layout. For OpenCL you can pass this offset as a kernel parameter.

There is a separate project in the solution called GLSL_instancing, to test this instancing. The implementation is in InitShaders();

Initializing OpenCL

Initializing OpenCL happens as usual, except for interop we need to pass the current OpenGL context:

glCtx = wglGetCurrentContext();
glDC = wglGetCurrentDC();
 
cl_context_properties cps[7] = {0,0,0,0,0,0,0};
cps[0] = CL_CONTEXT_PLATFORM;
cps[1] = (cl_context_properties)platform;
cps[2] = CL_GL_CONTEXT_KHR;
cps[3] = (cl_context_properties)pGLContext;
cps[4] = CL_WGL_HDC_KHR;
cps[5] = (cl_context_properties)pGLDC;
int ciErrNum;
cl_context retContext = clCreateContextFromType(cps, CL_DEVICE_TYPE_GPU,NULL,NULL,&ciErrNum);

There is a separate project called OpenCL_initialize to show the initialization. In the OpenCL_GL_interop project, the initialization happens in the InitCL method.

Acquiring and releasing the buffer

For each frame, before rendering all the instances, you can acquire the graphics buffer, run the OpenCL kernels and release the buffer with the following code snippet:

glFinish();
cl_mem clBuffer = g_interopBuffer->getCLBUffer();
cl_int ciErrNum = CL_SUCCESS;
ciErrNum = clEnqueueAcquireGLObjects(g_cqCommandQue, 1, &clBuffer, 0, 0, NULL);
oclCHECKERROR(ciErrNum, CL_SUCCESS);
int numObjects = NUM_OBJECTS;
int offset = (sizeof(cube_vertices) )/4;
ciErrNum = clSetKernelArg(g_interopKernel, 0, sizeof(int), &offset);
ciErrNum = clSetKernelArg(g_interopKernel, 1, sizeof(int), &numObjects);
ciErrNum = clSetKernelArg(g_interopKernel, 2, sizeof(cl_mem), (void*)&clBuffer );
size_t	numWorkItems = workGroupSize*((NUM_OBJECTS + (workGroupSize-1)) / workGroupSize);
ciErrNum = clEnqueueNDRangeKernel(g_cqCommandQue, g_interopKernel, 1, NULL, &numWorkItems, &workGroupSize,0 ,0 ,0);
oclCHECKERROR(ciErrNum, CL_SUCCESS);
ciErrNum = clEnqueueReleaseGLObjects(g_cqCommandQue, 1, &clBuffer, 0, 0, 0);
oclCHECKERROR(ciErrNum, CL_SUCCESS);
clFinish(g_cqCommandQue);

Note that there is a more efficient way of synchonizing the buffers instead of using glFinish and clFinish using the ARB_cl_event extension. I’ll implement and talk about that another time.

The OpenCL Kernel

The OpenCL kernel for this example is extremely simple, it just adds 0.01 to the y component of all positions:

__kernel void interopKernel( const int startOffset, const int numNodes, __global float *g_vertexBuffer)
{
	int nodeID = get_global_id(0);
	if( nodeID < numNodes )
	{
		g_vertexBuffer[nodeID*4 + startOffset+1] += 0.01;
	}
}

This will be replaced by particle or simple rigid body dynamics with collision detection in an upcoming posting.

The screenshot at the beginning of the article is taken from the sample code: a OpenGL/glut demo that can render 125.000 instanced cubes in realtime, around 70 frames per second on my laptop with Radeon 6570M with GPU drivers supporting OpenCL 1.1. When increasing this to 1 million cubes it still runs at ‘interactive’ rates of a few frames per second. The demo also works on my NVIDIA GTX 260 desktop with OpenCL 1.0.

Download

You can download the full source code and precompiled executables from my experiments repo at github. The code is available under the permissive zlib license. To build it, click on buildvs2008.bat to generate Visual Studio 2008 project files using premake4 and then open the buildmsvc2008MySolution.sln. The glut demo is only tested on Windows 7 with Visual Studio. Feel free to contribute a port for your favorite OpenCL platform, such as Linux or Mac OSX.

Convex decomposition

Convex polyhedral meshes can be created manually using authoring tools, or generated automatically from concave triangle meshes using convex decomposition methods. Khaled Mammou just released a brand new library for Hierarchical Approximate Convex Decomposition of 3D Meshes (HACD) that can be downloaded here https://sourceforge.net/projects/hacd

I plan to try out his convex decomposition method and discuss this in an upcoming blog posting.

For our open source Bullet physics engine, I’ve been distributing the source code in a way that should make it as easy as possible to build out-of-the box. This means that for all supported platforms, the user (a developer who downloaded the Bullet SDK) should be able to download and unzip the zipfile or tarball on his machine, and get started as soon as possible. It should be hassle-free for the user but also for me, so I rather don’t manual updating too many files for each release.

Aside from all the different platforms, we need to also support various compilers, compiler settings and integrated developer environments (IDEs). Common platforms are Windows, Mac OSX, iPhone, Linux as well as PlayStation 3 and XBox 360. Some common compilers are Visual Studio compiler, GCC, SN Systems and LLVM.

Here are a couple of build systems and modifications that I tried or considered to try:

Visual Studio project files. Shipping manual generated visual studio files works hassle-free for the user, but isn’t hassle-free for myself especially if you want to support all versions from MSVC 6 up to MSVC 2010. Obviously it is also not cross-platform so it needs to be combined with another build system. For example autotools.

autotools: for most unix flavors, autotools does a great job. It is often already installed and is fairly hassle-free, as long as the user doesn’t run into version compatibilities of automake, autoconf or libtool. It is a bit of a hassle for me, because I’m not too familiar with autotools and can only provide most basic support. A bigger issue is that autotools doesn’t support IDEs such as Xcode.

Xcode, the environment for Mac OSX and iPhone, requires its own project files. Shipping manual generated project files is a burden, when dealing with versions and platform settings.

jam and msvcgen: jam is a fast build system and it is small enough to ship the entire jam source code together with my own project (it is just a few hundred kilobytes with no external dependencies). The msvcgen extension could autogenerate standalone Visual Studio project files from MSVC 6 onwards, so that was a nice extra. For several years I’ve been shipping the Bullet SDK with autotools + jam and msvcgen autogenerated Visual Studio projects for MSVC 6, 7 and 2005. No proper support for XCode, until I noticed cmake.

cmake: this is almost a dream meta build system but unfortunately it cannot properly generate distributable build systems. For example the generated Visual Studio project files only work on the local machine. I’ve been hacking the cmake source code so that it does generate distributable project files, and submitted a few patches back to cmake. Unfortunately, the main cmake developers don’t want to support distributable project file generation, and I felt they were very reluctant to discuss further changes to support distributable project files. For example, I need the option to avoid creating copy rules that depend on cmake being installed. Furthermore any environment variables should not be expanded in absolute paths but stay environment variables for shipping project files (for example DXSDK_DIR, ATISTREAMSDKROOT or NVSDKCOMPUTE_ROOT for some recent OpenCL and DirectCompute accelerated optional modules). This means that I need to keep on using and updating a forked version of cmake to generate and distribute MSVC projectfiles. As a side note: the wxWidgets project even created their own build system, just because of this cmake shortcoming. Another shortcoming of cmake is lack of multiple compiler support, so generating projects for both PlayStation PPU and SPU is not possible. After bringing up my build system issue on the PS3 Devnet forums, someone mentioned premake.

premake is a very promising meta build system and I keep on thinking of trying it out. I’ve heard people who create PS3 and XBox 360 project files, and it supports most other platforms. Premake can be optionally extended using Lua, but it is not a requirement for Lua to be installed, unlike the Python requirement for scons. Unfortunately, I’ve heard that premake has some issues with dependency tracking, has less features that cmake and it is not widely supported yet. This means that integrating it into another project might become a hassle.

This leaves me to either wait until premake matures and becomes more widely used, or writing my own meta-meta build system that can generate both cmake, premake and other project files.