Android NDK Game Development Cookbook

Here is the list of all the prerequisites you will need to start developing games for Android:

Former versions of SDK/NDK for Windows required a Cygwin environment, a Linux-like environment for Windows, to be installed. Up-to-date versions of these tools can run natively on Windows without any intermediate layer. We will focus on the Cygwin-less environment and will do all of the development without IDE. You heard it right, we will just use the command line. All the examples in this book were written and debugged on a Windows PC.

To compile native Windows applications presented in this book, you will need a decent C++ compiler, such as the MinGW package with a GCC toolchain. Using Microsoft Visual Studio is also possible.

All tools have pretty decent GUI installers (see the following image, that shows the Android SDK Manager from SDK R21) so you don't have to use the command line.

For the Windows environment, you need the MinGW GCC toolchain. The easy to install all-in-one package can be found at http://www.equation.com, in the Programming Tools section, Fortran, C, C++ subsection. Alternatively, you can download the official installer from http://www.mingw.org. We will use the one from www.equation.com

You need to set some environment variables to let the tools know where the files are located. The JAVA_HOME variable should point to the Java Development Kit folder. The NDK_HOME variable should point to the Android NDK installation folder, and ANDROID_HOME should point to the Android SDK folder (note the double backslash). We used the following environment variable values:

JAVA_HOME=D:\Java\jdk1.6.0_23

NDK_HOME=D:\ndk

ANDROID_HOME=D:\\android-sdk-windows

The final configuration looks similar to the one shown in the following screenshot, which shows the Windows Environment Variables dialog box:

After MinGW has been successfully installed, you should also add the bin folder from its installation folder to the PATH environment variable. For example, if MinGW is installed to C:\MinGW, then PATH should contain the C:\MinGW\bin folder.

We assume you already have an Ubuntu/Debian system with the apt package manager. Refer to http://wiki.debian.org/Apt for details.

Carry out the following steps to install the required basic tools:

There is a nice one-liner script that helps you automatically detect the OpenJDK home directory. It essentially resolves the link /usr/bin/javac to the full path and returns the directory part of the path.

  JAVA_HOME=$(readlink -f /usr/bin/javac | sed "s:bin/javac::")

Let us set up the directory structure of our project (see the following screenshot):

This is a typical structure for any Android project. We will create all the required files manually rather than using Android tools.

Place the Java Activity code into the App1\src\com\packtpub\ndkcookbook\app1\App1Activity.java file, which should look as follows:

package com.packtpub.ndkcookbook.app1;
import android.app.Activity;
public class App1Activity extends Activity
{
};

The localizable application name should go to App1\res\values\strings.xml. The string parameter app_name is used in the AndroidManifest.xml file to specify the user-readable name of our application, as seen in the following code:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">App1</string>
</resources>

Now we need to write more scripts for Apache Ant and the Android SDK build system. They are necessary to build the .apk package of your application.

With all the listed files in place, we can now build the project and install it on an Android device by carrying out the following steps:

The application can now be started from your Android launcher (named App1). You will see just a black screen. You can exit the application using the BACK button.

Don't forget to put the application icon into App1\res\drawable\icon.png. Refer to the book's code bundle if you want to build the app quickly, or put your own icon there. 72 x 72 32-bit will do just fine. You can find the official Android icons guidelines at http://developer.android.com/design/style/iconography.html.

The official documentation on the AndroidManifest.xml file can be found at http://developer.android.com/guide/topics/manifest/manifest-intro.html.

Furthermore, you can update your applications without uninstalling the previous version using the adb -r command-line switch in the following way:

>adb install -r App1-debug.apk

Otherwise, before installing a new version of your application you will have to uninstall the existing one using the following command:

>adb uninstall <package-name>

We need to copy all the files from our App1 project to save time while creating the initial project files. This recipe will focus on the changes to be made to the App1 project in order to add the C++ code to it.

Carry out the following steps to create a placeholder for our C++ code:

You can use the adb command to view the device log. A nice clean formatted log with timestamps can be created using the following command:

>adb logcat -v time > 1.txt

The actual output from your device will look similar to the following command:

05-22 13:00:13.861 I/App2    ( 2310): Hello World!

Look through the list of the available toolchains before proceeding. You can find all the available toolchains in the $(NDK_ROOT)/toolchains/ folder.

The parameter NDK_TOOLCHAIN_VERSION in Application.mk corresponds to one of the available toolchains. In NDK r9b, you can switch between three GCC versions—4.6, and 4.7, which are marked as deprecated and will be removed from the next NDK releases, and 4.8. And two Clang versions—Clang3.2, which is also marked as deprecated, and Clang3.3. The default toolchain in the NDK r9b is still GCC 4.6.

Starting from the NDK r8e, you can just specify clang as the value of NDK_TOOLCHAIN_VERSION. This option will select the most recent version of the available Clang toolchain.

The toolchains are discovered by the $(NDK_ROOT)/build/core/init.mk script, so you can define your own toolchain in a folder named <ABI>-<ToolchainName> and use it in Application.mk.

Find out the architecture of your Android-based device. You can do it using the adb command as follows:

>adb shell cat /proc/cpuinfo

The following are the two approaches to pick an appropriate set of CPU architectures:

The main pitfall of the fat binaries is the resulting .apk size, as separate native code versions are compiled for each of the specified architectures. If your application heavily uses third-party libraries, the package size can become an issue. Plan your deliverables wisely.

We assume that the reader is somewhat familiar with OpenGL and the GL Shading Language (GLSL). Refer to http://www.opengl.org/documentation for the desktop OpenGL, and http://www.khronos.org/opengles for the mobile OpenGL ES documentation.

We will not go into all the details about the OpenGL ES programming here, and will instead focus on a minimal application (App3) that should initialize the GLView in Java; create fragment and vertex programs, create and fill the vertex array consisting of two triangles that form a single quadrilateral, and then render them with a texture, which is updated from g_FrameBuffer contents. This is it—just draw the offscreen framebuffer. The following is the code to draw the full-screen quad textured with the offscreen buffer content:

  const GLfloat vVertices[] = { -1.0f, -1.0f, 0.0f,
                                -1.0f,  1.0f, 0.0f,
                                 1.0f, -1.0f, 0.0f,
                                -1.0f,  1.0f, 0.0f,
                                1.0f, -1.0f, 0.0f,
                                1.0f,  1.0f, 0.0f
                              };

  const GLfloat vCoords[]   = {  0.0f,  0.0f, 0.0f,
                                 0.0f,  1.0f, 0.0f,
                                 1.0f,  0.0f, 0.0f,
                                 0.0f,  1.0f, 0.0f,
                                 1.0f,  0.0f, 0.0f,
                                 1.0f,  1.0f, 0.0f
                              };
  glUseProgram ( g_ProgramObject );

These attribute variables are declared in a vertex shader. See the value of g_vShaderStr[] in the preceding code.

  GLint Loc1 = glGetAttribLocation(g_ProgramObject,"vPosition");
  GLint Loc2 = glGetAttribLocation(g_ProgramObject,"vCoords");

  glBindBuffer( GL_ARRAY_BUFFER, 0 );
  glBindBuffer( GL_ELEMENT_ARRAY_BUFFER, 0 );
  glVertexAttribPointer(
    Loc1, 3, GL_FLOAT, GL_FALSE, 0, vVertices );
  glVertexAttribPointer(
    Loc2, 3, GL_FLOAT, GL_FALSE, 0, vCoords   );
  glEnableVertexAttribArray( Loc1 );
  glEnableVertexAttribArray( Loc2 );

  glDisable( GL_DEPTH_TEST );
  glDrawArrays( GL_TRIANGLES, 0, 6 );
  glUseProgram( 0 );
  glDisableVertexAttribArray( Loc1 );
  glDisableVertexAttribArray( Loc2 );

We also need a few JNI callbacks. The first one handles the surface size changes, as seen in the following code:

  JNIEXPORT void JNICALLJava_com_packtpub_ndkcookbook_app3_App3Activity_SetSurfaceSize(JNIEnv* env, jclass clazz, int Width, int Height )
  {
    LOGI( "SurfaceSize: %i x %i", Width, Height );
    g_Width  = Width;
    g_Height = Height;
    GLDebug_LoadStaticProgramObject();
    glGenTextures( 1, &g_Texture );
    glBindTexture( GL_TEXTURE_2D, g_Texture );

Disable mip-mapping through the following code:

    glTexParameteri( GL_TEXTURE_2D,GL_TEXTURE_MIN_FILTER, GL_NEAREST );
    glTexImage2D( GL_TEXTURE_2D, 0, GL_RGBA,ImageWidth, ImageHeight, 0, GL_RGBA,GL_UNSIGNED_BYTE, g_FrameBuffer );
  }

The second callback does the actual frame rendering:

  JNIEXPORT void JNICALL Java_com_packtpub_ndkcookbook_app3_App3Activity_DrawFrame( JNIEnv* env, jobject obj )
  {

Invoke our frame rendering callback through the following code:

    OnDrawFrame();

    glActiveTexture( GL_TEXTURE0 );
    glBindTexture( GL_TEXTURE_2D, g_Texture );
    glTexSubImage2D( GL_TEXTURE_2D, 0, 0, 0,ImageWidth, ImageHeight, GL_RGBA,GL_UNSIGNED_BYTE, g_FrameBuffer );
    GLDebug_RenderTriangle();
  }

To perform what we just discussed, we have to implement some sort of abstraction on top of the NDK, POSIX, and Windows API. Such an abstraction should feature at least the following:

To render a framebuffer on the screen, we need to create a so-called device context with an associated bitmap, and add the WM_PAINT event handler to the window function.

To handle the keyboard and mouse events, we add the WM_KEYUP and WM_MOUSEMOVE cases to the switch statement in the previous program. Actual event handling is performed in the externally provided routines OnKeyUp() and OnMouseMove(), which contain our game logic.

The following is the complete source code of the program (some omitted parts, similar to the previous example, are omitted). The functions OnMouseMove(), OnMouseDown(), and OnMouseUp() accept two integer arguments that store the current coordinates of the mouse pointer. The functions OnKeyUp() and OnKeyDown() accept a single argument—the pressed (or released) key code:

#include <windows.h>

HDC hMemDC;
HBITMAP hTmpBmp;
BITMAPINFO BmpInfo;

In the following code, we store our global RGBA framebuffer:

unsigned char* g_FrameBuffer;

We do all OS-independent frame rendering in this callback. We draw a simple XOR pattern (http://lodev.org/cgtutor/xortexture.html) into the framebuffer as follows:

void DrawFrame()
{
  int x, y;
  for (y = 0 ; y < ImageHeight ; y++)
  {
    for (x = 0 ; x < ImageWidth ; x++)
    {
      int Ofs = y * ImageWidth + x;
      int c = (x ^ y) & 0xFF;
      int RGB = (c<<16) | (c<<8) | (c<<0) | 0xFF000000;
      ( ( unsigned int* )g_FrameBuffer )[ Ofs ] =	RGB;
    }
  }
}

The following code shows the WinAPI window function:

LRESULT CALLBACK MyFunc(HWND h, UINT msg, WPARAM w, LPARAM p)
{
  PAINTSTRUCT ps;
  switch(msg)
  {
  case WM_DESTROY:
    PostQuitMessage(0);
break;
  case WM_KEYUP:
    OnKeyUp(w);
break;
  case WM_KEYDOWN:
    OnKeyDown(w);
break;
  case WM_LBUTTONDOWN:
    SetCapture(h);
    OnMouseDown(x, y);
break;
  case WM_MOUSEMOVE:
    OnMouseMove(x, y);
break;
  case WM_LBUTTONUP:
    OnMouseUp(x, y);
    ReleaseCapture();
break;
  case WM_PAINT:
    dc = BeginPaint(h, &ps);
    DrawFrame();         

Transfer the g_FrameBuffer to the bitmap through the following code:

    SetDIBits(hMemDC, hTmpBmp, 0, Height,g_FrameBuffer, &BmpInfo, DIB_RGB_COLORS);
    SelectObject(hMemDC, hTmpBmp);

And copy it to the window surface through the following code:

    BitBlt(dc, 0, 0, Width, Height, hMemDC, 0, 0, SRCCOPY);
    EndPaint(h, &ps);
break;
  }
  return DefWindowProc(h, msg, w, p);
}

Since our project contains a make file the compilation can be done via a single command:

>make all

Running this program should produce the result as shown in the following screenshot, which shows the Win_Min2 example running on Windows:

The main difference between the Android and Windows implementation of a main loop can be summarized in the following way. In Windows, we are in control of the main loop. We literally declare a loop, which pulls messages from the system, handles input, updates the game state, and render s the frame (marked green in the following figure). Each stage invokes an appropriate callback from our portable game (denoted with blue color in the following figure). On the contrary, the Android part works entirely differently. The main loop is moved away from the native code and lives inside the Java Activity and GLSurfaceView classes. It invokes the JNI callbacks that we implement in our wrapper native library (shown in red). The native wrapper invokes our portable game callbacks. Let's summarize it in the following way:

The rest of the book is centered on this kind of architecture and the game functionality will be implemented inside these portable On...() callbacks.

There is yet another important note. Responding to timer events to create animation can be done on Windows with the SetTimer() call and the WM_TIMER message handler. We get to that in Chapter 2, Porting Common Libraries, when we speak about rigid body physics simulations. However, it is much better to organize a fixed time-step main loop, which is explained later in the book.

In Android, the application initialization phase is different, and since we use a mixed Java plus C++ approach, the entry points will be different. In C++, we are tied to, int main() or DWORD WinMain() functions; whereas in Android it is up to us to choose which JNI function we may call from our Java starter code. Event handling and rendering the initialization code are also quite different, too. To do so, we mark sections of the code with pre-processor definitions and put the different OS code into different files—Wrappers_Android.h and Wrappers_Windows.h.

We use the standard macros to detect the OS for which the program is being compiled: Windows-targeted compilers provide the _WIN32 symbol definition, and the __linux__ macro is defined on any Linux-based OS, including Android. However, the __linux__ defination is not enough, since some of the APIs are missing in Android. The macro ANDROID is a non-standard macro and we pass the -DANDROID switch to our compiler to identify the Android target in our C++ code. To make this for every source file, we modify the CFLAGS variable in the Android.mk file.

Finally, when we write the low-level code, the detection looks like the following code:

#if defined(_WIN32)
// windows-specific code
#elif defined(ANDROID)
// android-specific code
#endif

For example, to make an entry point look the same for both the Android and Windows versions, we write the following code:

#if defined(_WIN32)
#  define APP_ENTRY_POINT()  int main()
#elif defined(ANDROID)
#  define APP_ENTRY_POINT() int App_Init()
#endif

Later we will replace the int main() definition with the APP_ENTRY_POINT() macro.

To detect more operating systems, compilers, and CPU architectures, it is useful to check out a list of predefined macros at http://predef.sourceforge.net.

Recall the folder structure of the App3 project. We have the src and jni folders inside our App2 folder. The jni/Android.mk, jni/Application.mk, and build.xml files specify the Android build process. To enable the Windows executable creation, we add a file named Makefile, which references the main.cpp file.

The following is the content of Makefile:

CC = gcc
all:
  $(CC) -o main.exe main.cpp -lgdi32 -lstdc++

The idea is that when we add more and more OS-independent logic, the code resides in .cpp files, which do not reference any OS-specific headers or libraries. For the first few chapters, this simple framework that delegates frame rendering and event handling to portable OS-independent functions (OnDrawFrame(), OnKeyUp() and so on) is enough.

All of our examples from the subsequent chapters are buildable for Windows from the command line using a single make all command. Android native code is buildable with a single ndk-build command. We will use this convention throughout the rest of the book.

A detailed explanation of the signing procedure on Android is given in the developer manual at http://developer.android.com/tools/publishing/app-signing.html. We will focus on the signing from the command line and automating the entire process via batch files.

First of all, we need to rebuild the project and create a release version of the .apk package. Let's do it with our App2 project:

>ndk-build -B
>ant release

You should see a lot of text output from Ant, which ends with something like the following command:

-release-nosign:
[echo] No key.store and key.alias properties found in build.properties.
[echo] Please sign App2\bin\App2-release-unsigned.apk manually
[echo] and run zipalign from the Android SDK tools.

Let us generate a self-signed release key using keytool from the JDK through the following command:

>keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000

Fill out all the fields necessary for the key, as in the following command:

Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  Sergey Kosarevsky
What is the name of your organizational unit?
  [Unknown]:  SD
What is the name of your organization?
  [Unknown]:  Linderdaum
What is the name of your City or Locality?
  [Unknown]:  St.Petersburg
What is the name of your State or Province?
  [Unknown]:  Kolpino
What is the two-letter country code for this unit?
  [Unknown]:  RU
Is CN=Sergey Kosarevsky, OU=SD, O=Linderdaum, L=St.Petersburg, ST=Kolpino, C=RU correct?
  [no]:  yes

Generating 2048 bit RSA key pair and self-signed certificate (SHA1withRSA) with a validity of 10000 days
        for: CN=Sergey Kosarevsky, OU=SD, O=Linderdaum, L=St.Petersburg, ST=Kolpino, C=RU
Enter key password for <alias_name>
        (RETURN if same as keystore password):
[Storing my-release-key.keystore]

Now we are ready to proceed with the actual application signing. Use the jarsigner tool from the JDK through the following code:

>jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -keystore my-release-key.keystore bin\App2-release-unsigned.apk alias_name

This command is interactive, and it will require the user to enter the keystore password and the key password. However, we can provide passwords in a batch file in the following way:

>jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -keystore my-release-key.keystore -storepass 123456 –keypass 123456 bin\App2-release-unsigned.apk alias_name

Passwords should match what you entered while creating your release key and keystore.

There is one more step left before we can safely publish our .apk package on Google Play. Android applications can access uncompressed content within .apk using mmap() calls. Yet, mmap() may imply some alignment restrictions on the underlying data. We need to align all uncompressed data within .apk on 4-byte boundaries. Android SDK has the zipalign tool to do it, as seen in the following command:

>zipalign -v 4 bin\App2-release-unsigned.apk App2-release.apk

Now our .apk is ready to be published.