In-Depth: Native Client for Dummies

[In this reprinted #altdevblogaday piece, AMD's principal physics engineer Erwin Coumans provides a quick but informative tutorial for building a 3D Native client that you can deploy to the Chrome Web Store.] Today's Chrome web browser update means you can develop, sell, download, and play 3D games written in C++ right from the Chrome Web Store, without a plug-in. 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:

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.

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:

I recommend checking out the links below if you are interested to learn more. Enjoy! Useful Links:

[This piece was reprinted from #AltDevBlogADay, a shared blog initiative started by @mike_acton devoted to giving game developers of all disciplines a place to motivate each other to write regularly about their personal game development passions.]