Android.NDK.Beginner.Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 436 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Cover
Copyright
Credits
About the Author
About the Reviewers
www.PacktPub.com
Table of Contents
Preface
Chapter 1: Setting Up your Environment
- Getting started with Android development
- Setting up Windows
- Time for action – preparing Windows for Android development
- Installing Android development kits on Windows
- Time for action – installing Android SDK and NDK on Windows
- Setting up Mac OS X
- Time for action – preparing Mac OS X for Android development
- Installing Android development kits on Mac OS X
- Time for action – installing Android SDK and NDK on Mac OS X
- Setting up Linux
- Time for action – preparing Ubuntu Linux for Android development
- Installing Android development kits on Linux
- Time for action – installing Android SDK and NDK on Ubuntu
- Setting up the Eclipse development environment
- Time for action – installing Eclipse
- Emulating Android
- Time for action – creating an Android virtual device
- Developing with an Android device on Windows and Mac OS X
- Time for action – setting up your Android device on Windows and Mac OS X
- Developing with an Android device on Linux
- Time for action – setting up your Android device on Ubuntu
- Troubleshooting a development device
- Summary
Chapter 2: Creating, Compiling, and Deploying Native Projects
- Compiling and deploying NDK sample applications
- Time for action – compiling and deploying the hellojni sample
- Exploring Android SDK tools
  - Android debug bridge
  - Project configuration tool
- Creating your first Android project using eclipse
- Time for action – initiating a Java project
  - Introducing Dalvik
- Interfacing Java with C/C++
- Time for action – calling C code from Java
  - More on Makefiles
- Compiling native code from Eclipse
- Time for action – creating a hybrid Java/C/C++ project
- Summary
Chapter 3: Interfacing Java and C/C++ with JNI
- Working with Java primitives
- Time for action – building a native key/value store
- Referencing Java objects from native code
- Time for action – saving a reference to an object in the Store
  - Local and global JNI references
- Throwing exceptions from native code
- Time for action – raising exceptions from the Store
  - JNI in C++
- Handling Java arrays
- Time for action – saving a reference to an object in the Store
  - Checking JNI exceptions
- Summary
Chapter 4: Calling Java Back from Native Code
- Synchronizing Java and native threads
- Time for action – running a background thread
  - Attaching and detaching threads
  - More on Java and native code lifecycles
- Calling Java back from native code
- Time for action – invoking Java code from a native thread
  - More on callbacks
  - JNI method definitions
- Processing bitmaps natively
- Time for action – decoding camera feed from native code
- Summary
Chapter 5: Writing a Fully-native Application
- Creating a native activity
- Time for action – creating a basic native activity
- Handling activity events
- Time for action – handling activity events
  - More on Native App Glue
- Accessing window and time natively
- Time for action – displaying raw graphics and implementing a timer
- Summary
Chapter 6: Rendering Graphics with OpenGL ES
- Initializing OpenGL ES
- Time for action – initializing OpenGL ES
- Reading PNG textures with the asset manager
- Time for action – loading a texture in OpenGL ES
- Drawing a sprite
- Time for action – drawing a Ship sprite
- Rendering a tile map with vertex buffer objects
- Time for action – drawing a tile-based background
- Summary
Chapter 7: Playing Sound with OpenSL ES
- Initializing OpenSL ES
- Time for action – creating OpenSL ES engine and output
  - More on OpenSL ES philosophy
- Playing music files
- Time for action – playing background music
- Playing sounds
- Time for action – creating and playing a sound buffer queue
  - Event callback
- Recording sounds
- Summary
Chapter 8: Handling Input Devices and Sensors
- Interacting with Android
- Time for action – handling touch events
- Detecting keyboard, D-Pad, and Trackball events
- Time for action – handling keyboard, D-Pad, and trackball, natively
- Probing device sensors
- Time for action – turning your device into a joypad
- Summary
Chapter 9: Porting Existing Libraries to Android
- Developing with the Standard Template Library
- Time for action – embedding GNU STL in DroidBlaster
  - Static versus shared
  - STL performances
- Compiling Boost on Android
- Time for action – embedding Boost in DroidBlaster
- Porting third-party libraries to Android
- Time for action – compiling Box2D and Irrlicht with the NDK
  - GCC optimization levels
- Mastering Makefiles
  - Makefile variables
  - Makefile Instructions
- Summary
Chapter 10: Towards Professional Gaming
- Simulating physics with Box2D
- Time for action – simulating physics with Box2D
- Running a 3D engine on Android
- Time for action – rendring 3D graphics with Irrlicht
  - More on Irrlicht scene management
- Summary
Chapter 11: Debugging and Troubleshooting
- Debugging with GDB
- Time for action – debugging DroidBlaster
- Stack trace analysis
- Time for action – analysing a crash dump
  - More on crash dumps
- Performance analysis
- Time for action – running GProf
  - How it works
  - ARM, thumb, and NEON
- Summary
- Afterword
Index

Android NDK

Beginner's Guide

Discover the nave side of Android and inject the power

of C/C++ in your applicaons

Sylvain Ratabouil

BIRMINGHAM - MUMBAI

Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >

Android NDK

Beginner's Guide

or transmied in any form or by any means, without the prior wrien permission of the

publisher, except in the case of brief quotaons embedded in crical arcles or reviews.

Every eort has been made in the preparaon of this book to ensure the accuracy of the

informaon presented. However, the informaon contained in this book is sold without

warranty, either express or implied. Neither the author nor Packt Publishing, and its dealers

and distributors will be held liable for any damages caused or alleged to be caused directly

or indirectly by this book.

Packt Publishing has endeavored to provide trademark informaon about all of the companies

and products menoned in this book by the appropriate use of capitals. However, Packt

Publishing cannot guarantee the accuracy of this informaon.

First published: January 2012

Producon Reference: 1200112

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham B3 2PB, UK.

ISBN 978-1-84969-152-9

www.packtpub.com

Cover Image by Marcus Grandon (marcusgrandon@mac.com)

Credits

Author

Sylvain Ratabouil

Reviewers

Marko Gargenta

Dr. Frank Grützmacher

Robert Mitchell

Acquision Editor

Sarah Cullington

Lead Technical Editor

Dayan Hyames

Technical Editor

Pramila Balan

Copy Editor

Laxmi Subramanian

Project Coordinator

Jovita Pinto

Proofreader

Lynda Sliwoski

Indexer

Hemangini Bari

Graphics

Valenna D'silva

Producon Coordinators

Prachali Bhiwandkar

Melwyn D'sa

Nilesh Mohite

Cover Work

Alwin Roy

About the Author

Sylvain Ratabouil is a conrmed IT consultant with experience in C++ and Java

technologies. He worked for the space industry and got involved in aeronauc projects at

Valtech Technologies where he now takes part in the Digital Revoluon.

Sylvain earned the master's degree in IT from Paul Sabaer University in Toulouse and did

M.Sc. in Computer Science from Liverpool University.

As a technology lover, he is passionate about mobile technologies and cannot live or sleep

without his Android smartphone.

I would like to thank Steven Wilding for oering me to write this book;

Sneha Harkut and Jovita Pinto for awaing me with so much paence;

Reshma Sundaresan, and Dayan Hyames for pung this book on the

right track; Sarah Cullington for helping me nalizing this book;

Dr. Frank Grützmacher, Marko Gargenta, and Robert Mitchell for

all their helpful comments.

About the Reviewers

Dr. Frank Grützmacher has worked for several major German rms in the area of large

distributed systems. He was an early user of dierent Corba implementaons in the past.

He got his Ph.D. in the eld of electrical engineering, but with the focus on distributed

heterogeneous systems. In 2010, he was involved in a project, which changed parts of the

Android plaorm for a manufacturer. From there, he got his knowledge about the android

NDK and nave processes on this plaorm.

He has already worked as a reviewer for another Android 3.0 book.

Robert Mitchell is an MIT graduate with over 40 years experience in Informaon

Technology and is semirered. He has developed soware for all the big iron companies:

IBM, Amdahl, Fujitsu, Naonal Semiconductor, and Storage Technology. Soware companies

include Veritas and Symantec. Recent languages that he knows are Ruby and Java, with a

long background in C++.

www.PacktPub.com

Support les, eBooks, discount offers and more

You might want to visit www.PacktPub.com for support les and downloads related to

your book.

Did you know that Packt oers eBook versions of every book published, with PDF and ePub

les available? You can upgrade to the eBook version at www.PacktPub.com and as a print

book customer, you are entled to a discount on the eBook copy. Get in touch with us at

service@packtpub.com for more details.

At www.PacktPub.com, you can also read a collecon of free technical arcles, sign up for

a range of free newsleers and receive exclusive discounts and oers on Packt books and

eBooks.

http://PacktLib.PacktPub.com

Do you need instant soluons to your IT quesons? PacktLib is Packt's online digital book

library. Here, you can access, read and search across Packt's enre library of books.

Why Subscribe?

Fully searchable across every book published by Packt

Copy and paste, print and bookmark content

On demand and accessible via web browser

Free Access for Packt account holders

If you have an account with Packt at www.PacktPub.com, you can use this to access

PacktLib today and view nine enrely free books. Simply use your login credenals for

immediate access.

Table of Contents

Preface 1

Chapter 1: Seng Up your Environment 7

Geng started with Android development 7

Seng up Windows 8

Time for acon – preparing Windows for Android development 8

Installing Android development kits on Windows 12

Time for acon – installing Android SDK and NDK on Windows 13

Seng up Mac OS X 18

Time for acon – preparing Mac OS X for Android development 18

Installing Android development kits on Mac OS X 20

Time for acon – installing Android SDK and NDK on Mac OS X 20

Seng up Linux 22

Time for acon – preparing Ubuntu Linux for Android development 22

Installing Android development kits on Linux 27

Time for acon – installing Android SDK and NDK on Ubuntu 27

Seng up the Eclipse development environment 29

Time for acon – installing Eclipse 29

Emulang Android 33

Time for acon – creang an Android virtual device 33

Developing with an Android device on Windows and Mac OS X 37

Time for acon – seng up your Android device on Windows and Mac OS X 37

Developing with an Android device on Linux 39

Time for acon – seng up your Android device on Ubuntu 39

Troubleshoong a development device 42

Summary 43

Chapter 2: Creang, Compiling, and Deploying Nave Projects 45

Compiling and deploying NDK sample applicaons 46

Time for acon – compiling and deploying the hellojni sample 46

Table of Contents

[ ii ]

Exploring Android SDK tools 51

Android debug bridge 51

Project conguraon tool 54

Creang your rst Android project using eclipse 56

Time for acon – iniang a Java project 56

Introducing Dalvik 59

Interfacing Java with C/C++ 60

Time for acon – calling C code from Java 60

More on OpenSL ES philosophy

OpenSL ES is dierent from its graphics compatriot GLES, partly because it does not have a

long history to carry. It is constructed on an (more or less...) object-oriented principle based

on Objects and Interfaces. The following denions come from the ocial specicaon:

An object is an abstracon of a set of resources, assigned for a well-dened set

of tasks, and the state of these resources. An object has a type determined on its

creaon. The object type determines the set of tasks that an object can perform.

This can be considered similar to a class in C++.

An interface is an abstracon of a set of related features that a certain object

provides. An interface includes a set of methods, which are funcons of the

interface. An interface also has a type which determines the exact set of methods

of the interface. We can dene the interface itself as a combinaon of its type and

the object to which it is related.

An interface ID idenes an interface type. This idener is used within the source

code to refer to the interface type.

An OpenSL ES object is set up in few steps as follows:

1. Instanang it through a build method (belonging usually to the engine).

2. Realizing it to allocate necessary resources.

3. Retrieving object interfaces. A basic object only has a very limited set of operaons

(Realize(), Resume(), Destroy(), and so on). Interfaces give access to real

object features and describes what operaons can be performed on an object,

for example, a Play interface to play or pause a sound.

Any interfaces can be requested but only the one supported by the object is going to be

successfully retrieved. You cannot retrieve the record interface for an audio player because

it returns (somemes it is annoying!) SL_RESULT_FEATURE_UNSUPPORTED (error code 12).

In technical terms, an OpenSL ES interface is a structure containing funcon pointers

(inialized by OpenSL ES implementaon) with a self parameter to simulate C++ objects

and this , for example:

struct SLObjectItf_ {

SLresult (*Realize) (SLObjectItf self, SLboolean async);

SLresult (*Resume) ( SLObjectItf self, SLboolean async);

...

}

Chapter 7

[ 249 ]

Here, Realize(), Resume(), and so on are object methods that can be applied on an

SLObjectItf object. The approach is idencal for interfaces.

For more detailed informaon on what OpenSL ES can provide, refer to the specicaon

on Khronos web site: http://www.khronos.org/opensles as well as the OpenSL ES

documentaon in Android NDK docs directory. Android implementaon does not fully

respect the specicaon, at least for now. So do not be disappointed when discovering

that only a limited subset of the specicaon (especially sample codes) works on Android.

Playing music les

OpenSL ES is inialized, but the only thing coming out of speakers yet is silence! So what

about nding a nice piece of music (somemes abbreviated BGM) and playing it navely

with Android NDK? OpenSL ES provides the necessary stu to read music les such as MP3s.

Project DroidBlaster_Part7-1 can be used as a starng point

for this part. The resulng project is provided with this book

under the name DroidBlaster_Part7-2.

Time for action – playing background music

Let’s improve the code wrien in the previous part to read and play an MP3 le:

1. MP3 les are opened by OpenSL ES using a POSIX le descriptor, poinng to the

le. Improve jni/ResourceManager.cpp created in the previous chapters by

injecng a new structure ResourceDescriptor and appending a new method

descript():

#ifndef _PACKT_RESOURCE_HPP_

#define _PACKT_RESOURCE_HPP_

#include “Types.hpp”

#include <android_native_app_glue.h>

namespace packt {

struct ResourceDescriptor {

int32_t mDescriptor;

off_t mStart;

off_t mLength;

};

Playing Sound with OpenSL ES

[ 250 ]

class Resource {

public:

...

off_t getLength();

const void* bufferize();

ResourceDescriptor descript();

private:

...

};

}

#endif

2. Implementaon in ResourceManager.cpp, of course, makes use of the asset

manager API to open the descriptor and ll a ResourceDescriptor structure:

...

namespace packt {

...

ResourceDescriptor Resource::descript() {

ResourceDescriptor lDescriptor = { -1, 0, 0 };

AAsset* lAsset = AAssetManager_open(mAssetManager, mPath,

AASSET_MODE_UNKNOWN);

if (lAsset != NULL) {

lDescriptor.mDescriptor = AAsset_openFileDescriptor(

lAsset, &lDescriptor.mStart, &lDescriptor.

mLength);

AAsset_close(lAsset);

}

return lDescriptor;

}

3. Go back to jni/SoundService.hpp and dene two methods, playBGM()

and stopBGM(), to play a background music.

Also declare an OpenSL ES object for the music player along with the

following interfaces:

SLPlayItf: This plays and stops music les

SLSeekItf: This controls posion and looping

Chapter 7

[ 251 ]

...

namespace packt

{

class SoundService {

public:

...

status playBGM(const char* pPath);

void stopBGM();

...

private:

...

SLObjectItf mBGMPlayerObj; SLPlayItf mBGMPlayer;

SLSeekItf mBGMPlayerSeek;

};

}

#endif

4. Start implemenng jni/SoundService.cpp. Include Resource.hpp to get

access to asset le descriptors. Inialize new members in constructor and update

stop() to stop the background music automacally (or some users are not going

to be happy!):

#include “SoundService.hpp”

#include “Resource.hpp”

#include “Log.hpp”

namespace packt {

SoundService::SoundService(android_app* pApplication) :

mApplication(pApplication),

mEngineObj(NULL), mEngine(NULL),

mOutputMixObj(NULL),

mBGMPlayerObj(NULL), mBGMPlayer(NULL), mBGMPlayerSeek(NULL)

{}

...

void SoundService::stop() {

stopBGM();

Playing Sound with OpenSL ES

[ 252 ]

if (mOutputMixObj != NULL) {

(*mOutputMixObj)->Destroy(mOutputMixObj);

mOutputMixObj = NULL;

}

if (mEngineObj != NULL) {

(*mEngineObj)->Destroy(mEngineObj);

mEngineObj = NULL; mEngine = NULL;

}

...

5. Enrich SoundService.cpp with playback features by implemenng playBGM().

First we need to describe our audio setup through two main structures:

SLDataSource and SLDataSink. The rst describes the audio input channel

and the second, the audio output channel.

Here, we congure the data source as a MIME source so that le type gets detected

automacally from le descriptor. File descriptor is, of course, opened with a call to

ResourceManager::descript().

Data sink (that is, desnaon channel) is congured with the OutputMix object

created in the rst part of this chapter while inializing OpenSL ES engine

(and which refers to default audio output, that is, speakers or headset):

...

status SoundService::playBGM(const char* pPath) {

SLresult lRes;

Resource lResource(mApplication, pPath);

ResourceDescriptor lDescriptor = lResource.descript();

if (lDescriptor.mDescriptor < 0) {

Log::info(“Could not open BGM file”);

return STATUS_KO;

}

SLDataLocator_AndroidFD lDataLocatorIn;

lDataLocatorIn.locatorType = SL_DATALOCATOR_ANDROIDFD;

lDataLocatorIn.fd = lDescriptor.mDescriptor;

lDataLocatorIn.offset = lDescriptor.mStart;

lDataLocatorIn.length = lDescriptor.mLength;

SLDataFormat_MIME lDataFormat;

lDataFormat.formatType = SL_DATAFORMAT_MIME;

Chapter 7

[ 253 ]

lDataFormat.mimeType = NULL;

lDataFormat.containerType = SL_CONTAINERTYPE_UNSPECIFIED;

SLDataSource lDataSource;

lDataSource.pLocator = &lDataLocatorIn;

lDataSource.pFormat = &lDataFormat;

SLDataLocator_OutputMix lDataLocatorOut;

lDataLocatorOut.locatorType = SL_DATALOCATOR_OUTPUTMIX;

lDataLocatorOut.outputMix = mOutputMixObj;

SLDataSink lDataSink;

lDataSink.pLocator = &lDataLocatorOut;

lDataSink.pFormat = NULL;

...

6. Then create the OpenSL ES audio player. As always with OpenSL ES objects,

instanate it through the engine rst and then realize it. Two interfaces

SL_IID_PLAY and SL_IID_SEEK are imperavely required:

...

const SLuint32 lBGMPlayerIIDCount = 2;

const SLInterfaceID lBGMPlayerIIDs[] =

{ SL_IID_PLAY, SL_IID_SEEK };

const SLboolean lBGMPlayerReqs[] =

{ SL_BOOLEAN_TRUE, SL_BOOLEAN_TRUE };

lRes = (*mEngine)->CreateAudioPlayer(mEngine,

&mBGMPlayerObj, &lDataSource, &lDataSink,

lBGMPlayerIIDCount, lBGMPlayerIIDs, lBGMPlayerReqs);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mBGMPlayerObj)->Realize(mBGMPlayerObj,

SL_BOOLEAN_FALSE);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mBGMPlayerObj)->GetInterface(mBGMPlayerObj,

SL_IID_PLAY, &mBGMPlayer);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mBGMPlayerObj)->GetInterface(mBGMPlayerObj,

SL_IID_SEEK, &mBGMPlayerSeek);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

...

Playing Sound with OpenSL ES

[ 254 ]

7. Finally, using the play and seek interfaces, switch the playback in loop mode

(that is, music keeps playing) from the track beginning (that is, 0 ms) unl its

end (SL_TIME_UNKNOWN) and then start playing (SetPlayState() with

SL_PLAYSTATE_PLAYING).

...

lRes = (*mBGMPlayerSeek)->SetLoop(mBGMPlayerSeek,

SL_BOOLEAN_TRUE, 0, SL_TIME_UNKNOWN);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mBGMPlayer)->SetPlayState(mBGMPlayer,

SL_PLAYSTATE_PLAYING);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

return STATUS_OK;

ERROR:

return STATUS_KO;

}

...

8. The last method stopBGM() is shorter. It stops and then destroys the player:

...

void SoundService::stopBGM() {

if (mBGMPlayer != NULL) {

SLuint32 lBGMPlayerState;

(*mBGMPlayerObj)->GetState(mBGMPlayerObj,

&lBGMPlayerState);

if (lBGMPlayerState == SL_OBJECT_STATE_REALIZED) {

(*mBGMPlayer)->SetPlayState(mBGMPlayer,

SL_PLAYSTATE_PAUSED);

(*mBGMPlayerObj)->Destroy(mBGMPlayerObj);

mBGMPlayerObj = NULL;

mBGMPlayer = NULL;

mBGMPlayerSeek = NULL;

}

Chapter 7

[ 255 ]

9. Copy an MP3 le into the assets directory and name it bgm.mp3.

File bgm.mp3 is provided with this book in Chapter7/Resource.

10. Finally, in jni/DroidBlaster.cpp, start music playback right aer

SoundService is started:

#include “DroidBlaster.hpp”

#include “Log.hpp”

namespace dbs {

...

packt::status DroidBlaster::onActivate() {

packt::Log::info(“Activating DroidBlaster”);

if (mGraphicsService->start() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

if (mSoundService->start() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

mSoundService->playBGM

mBackground.spawn();

mShip.spawn();

mTimeService->reset();

return packt::STATUS_OK;

}

void DroidBlaster::onDeactivate() {

mGraphicsService->stop();

mSoundService->stop();

}

...

}

Playing Sound with OpenSL ES

[ 256 ]

What just happened?

We have discovered how to play a music clip from an MP3 le. Playback loops unl the

game is terminated. When using a MIME data source, the le type is auto-detected. Several

formats are currently supported format in Gingerbread including Wave PCM, Wave alaw,

Wave ulaw, MP3, Ogg Vorbis and so on. MIDI playback is currently not supported.

You may be surprised to see that, in the example, startBGM() and stopBGM() recreates

and destroys the audio player, respecvely. The reason is that there is currently no way to

change a MIME data source without completely recreang the OpenSL ES AudioPlayer

object. So although this technique is ne to play a long clip, it is not adapted for playing

short sound dynamically.

The way the sample code is presented here is typical of how OpenSL ES works. The OpenSL

ES engine object, that kind of object factory, creates an AudioPlayer object which cannot

do much in that state. First, it needs to be realized to allocate necessary resources. But that

is not enough. It needs to retrieve the right interfaces, like the SL_IID_PLAY interface to

change audio player state to playing/stopped. Then OpenSL API can be eecvely used.

That is quite some work, taking into account result vericaon (as any call is suscepble to

fail), which kind of cluers the code. Geng inside this API can take a lile bit more me

than usual, but once understood, these concepts become rather easy to deal with.

Playing sounds

The technique presented to play BGM from a MIME source is very praccal but sadly, not

exible enough. Recreang an AudioPlayer object is not necessary and accessing asset

les each me is not good in term of eciency.

So when it comes to playing sounds quickly in response to an event and generang them

dynamically, we need to use a sound buer queue. Each sound is preloaded or even

generated into a memory buer, and placed into a queue when playback is requested. No

need to access a le at runme!

A sound buer, in current OpenSL ES Android implementaon, can contain PCM data. PCM,

which stands for Pulse Code Modulaon, is a data format dedicated to the representaon of

digital sounds. It is the format used in CD and in some Wave les. A PCM can be Mono (same

sound on all speakers) or Stereo (dierent sound for le and right speakers if available).

PCM is not compressed and is not ecient in terms of storage (just compare a musical CD

with a data CD full of MP3). But this format is lossless and oers the best quality. Quality

depends on the sampling rate: analog sounds are represented digitally as a series of measure

(that is, sample) of the sound signal.

Chapter 7

[ 257 ]

A sound sample at 44100 Hz (that is 44100 measures per second) has a beer quality

but also takes more place than a sound sampled at 16000 Hz. Also, each measure can

be represented with a more or less ne degree of precision (the encoding). On current

Android implementaon:

A sound can use 8000 Hz, 11025 Hz, 12000 Hz, 16000 Hz, 22050 Hz, 24000 Hz,

32000 Hz, 44100 Hz, or 48000 Hz sampling,

A sample can be encoded on 8-bit unsigned or 16-bit signed (ner precision) in

lile-endian or big-endian.

In the following step-by-step tutorial, we are going to use a raw PCM le encoded over

16-bit in lile-endian.

Project DroidBlaster_Part7-2 can be used as a starng point for

this part. The resulng project is provided with this book under the

name DroidBlaster_Part7-3.

Time for action – creating and playing a sound buffer queue

First, let’s create a new object to hold sound buers:

1. In jni/Sound.hpp, create a new class Sound to manage a sound buer. It features

a method load() to load a PCM le and unload() to release it:

#ifndef _PACKT_SOUND_HPP_

#define _PACKT_SOUND_HPP_

class SoundService;

#include “Context.hpp”

#include “Resource.hpp”

#include “Types.hpp”

namespace packt {

class Sound {

public:

Sound(android_app* pApplication, const char* pPath);

const char* getPath();

status load();

status unload();

Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >

Playing Sound with OpenSL ES

[ 258 ]

private:

friend class SoundService;

private:

Resource mResource;

uint8_t* mBuffer; off_t mLength;

};

}

#endif

2. Sound loading implementaon is quite simple: it creates a buer with the same

size as the PCM le and loads all le content in it:

#include “Sound.hpp”

#include “Log.hpp”

#include <png.h>

#include <SLES/OpenSLES.h>

#include <SLES/OpenSLES_Android.h>

#include <SLES/OpenSLES_AndroidConfiguration.h>

namespace packt {

Sound::Sound(android_app* pApplication, const char* pPath) :

mResource(pApplication, pPath),

mBuffer(NULL), mLength(0)

{}

const char* Sound::getPath() {

return mResource.getPath();

}

status Sound::load() {

status lRes;

if (mResource.open() != STATUS_OK) {

return STATUS_KO;

}

mLength = mResource.getLength();

mBuffer = new uint8_t[mLength];

lRes = mResource.read(mBuffer, mLength);

mResource.close();

if (lRes != STATUS_OK) {

Log::error(“Error while reading PCM sound.”);

Chapter 7

[ 259 ]

return STATUS_KO;

} else {

return STATUS_OK;

}

status Sound::unload() {

delete[] mBuffer;

mBuffer = NULL; mLength = 0;

return STATUS_OK;

}

We can manage sound buers in the dedicated sound service.

3. Open SoudService.hpp and create a few new methods:

registerSound() to load and manage a new sound buer

playSound() to send a sound buer to the sound play queue

startSoundPlayer() to inialize the sound queue when

SoundService starts

A sound queue can be manipulated through SLPlayItf and SLBufferQueueItf

interfaces. Sound buers are stored in xed-size C++ array:

#ifndef _PACKT_SOUNDSERVICE_HPP_

#define _PACKT_SOUNDSERVICE_HPP_

#include “Sound.hpp”

#include “Types.hpp”

...

namespace packt {

class SoundService {

public:

...

Sound* registerSound(const char* pPath);

void playSound(Sound* pSound);

private:

status startSoundPlayer();

private:

Playing Sound with OpenSL ES

[ 260 ]

...

SLObjectItf mPlayerObj; SLPlayItf mPlayer;

SLBufferQueueItf mPlayerQueue;

Sound* mSounds[32]; int32_t mSoundCount;

};

}

#endif

4. Now, open jni/SoundService.cpp implementaon le. Update start()

to call startSoundPlayer() and load sound resources registered with

registerSound(). Also create a destructor to release these resources

when applicaon exits:

...

namespace packt {

SoundService::SoundService(android_app* pApplication) :

...,

mPlayerObj(NULL), mPlayer(NULL), mPlayerQueue(NULL),

mSounds(), mSoundCount(0)

{}

SoundService::~SoundService() {

for (int32_t i = 0; i < mSoundCount; ++i) {

delete mSounds[i];

mSoundCount = 0;

}

status SoundService::start() {

...

if (startSoundPlayer() != STATUS_OK) goto ERROR;

for (int32_t i = 0; i < mSoundCount; ++i) {

if (mSounds[i]->load() != STATUS_OK) goto ERROR;

}

return STATUS_OK;

ERROR:

packt::Log::error(“Error while starting SoundService”);

stop();

return STATUS_KO;

}

...

Chapter 7

[ 261 ]

Sound* SoundService::registerSound(const char* pPath) {

for (int32_t i = 0; i < mSoundCount; ++i) {

if (strcmp(pPath, mSounds[i]->getPath()) == 0) {

return mSounds[i];

}

Sound* lSound = new Sound(mApplication, pPath);

mSounds[mSoundCount++] = lSound;

return lSound;

}

...

5. Write startSoundPlayer(), beginning with the SLDataSource and

SLDataSink to describe the input and output channel. On the opposite to the BGM

player, the data format structure is not SLDataFormat_MIME (to open an MP3 le)

but a SLDataFormat_PCM with sampling, encoding, and endianness informaon.

Sounds need to be Mono (that is, only one sound channel for both le and right

speakers when available). The queue is created with the Android-specic extension

SLDataLocator_AndroidSimpleBufferQueue():

...

status SoundService::startSoundPlayer() {

SLresult lRes;

// Set-up sound audio source.

SLDataLocator_AndroidSimpleBufferQueue lDataLocatorIn;

lDataLocatorIn.locatorType =

SL_DATALOCATOR_ANDROIDSIMPLEBUFFERQUEUE;

// At most one buffer in the queue.

lDataLocatorIn.numBuffers = 1;

SLDataFormat_PCM lDataFormat;

lDataFormat.formatType = SL_DATAFORMAT_PCM;

lDataFormat.numChannels = 1; // Mono sound.

lDataFormat.samplesPerSec = SL_SAMPLINGRATE_44_1;

lDataFormat.bitsPerSample = SL_PCMSAMPLEFORMAT_FIXED_16;

lDataFormat.containerSize = SL_PCMSAMPLEFORMAT_FIXED_16;

lDataFormat.channelMask = SL_SPEAKER_FRONT_CENTER;

lDataFormat.endianness = SL_BYTEORDER_LITTLEENDIAN;

SLDataSource lDataSource;

lDataSource.pLocator = &lDataLocatorIn;

lDataSource.pFormat = &lDataFormat;

Playing Sound with OpenSL ES

[ 262 ]

SLDataLocator_OutputMix lDataLocatorOut;

lDataLocatorOut.locatorType = SL_DATALOCATOR_OUTPUTMIX;

lDataLocatorOut.outputMix = mOutputMixObj;

SLDataSink lDataSink;

lDataSink.pLocator = &lDataLocatorOut;

lDataSink.pFormat = NULL;

...

6. Then, in startSoundPlayer(), create and realize the sound player. We are going

to need its SL_IID_PLAY and also SL_IID_BUFFERQUEUE interface now available

thanks to the data locator congured in previous step:

...

const SLuint32 lSoundPlayerIIDCount = 2;

const SLInterfaceID lSoundPlayerIIDs[] =

{ SL_IID_PLAY, SL_IID_BUFFERQUEUE };

const SLboolean lSoundPlayerReqs[] =

{ SL_BOOLEAN_TRUE, SL_BOOLEAN_TRUE };

lRes = (*mEngine)->CreateAudioPlayer(mEngine, &mPlayerObj,

&lDataSource, &lDataSink, lSoundPlayerIIDCount,

lSoundPlayerIIDs, lSoundPlayerReqs);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mPlayerObj)->Realize(mPlayerObj, SL_BOOLEAN_FALSE);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mPlayerObj)->GetInterface(mPlayerObj, SL_IID_PLAY,

&mPlayer);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

lRes = (*mPlayerObj)->GetInterface(mPlayerObj,

SL_IID_BUFFERQUEUE, &mPlayerQueue);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

...

7. To nish with startSoundPlayer(), start the queue by seng it in the playing

state. This does not actually mean that a sound is played. The queue is empty so that

would not be possible. But if a sound gets enqueued, then it is automacally played:

...

lRes = (*mPlayer)->SetPlayState(mPlayer,

SL_PLAYSTATE_PLAYING);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

Chapter 7

[ 263 ]

return STATUS_OK;

ERROR:

packt::Log::error(“Error while starting SoundPlayer”);

return STATUS_KO;

}

...

8. Update method stop() to destroy the sound player and free sound buers:

...

void SoundService::stop() {

stopBGM();

if (mOutputMixObj != NULL) {

(*mOutputMixObj)->Destroy(mOutputMixObj);

mOutputMixObj = NULL;

}

if (mEngineObj != NULL) {

(*mEngineObj)->Destroy(mEngineObj);

mEngineObj = NULL; mEngine = NULL;

}

if (mPlayerObj != NULL) {

(*mPlayerObj)->Destroy(mPlayerObj);

mPlayerObj = NULL; mPlayer = NULL; mPlayerQueue = NULL;

}

for (int32_t i = 0; i < mSoundCount; ++i) {

mSounds[i]->unload();

}

...

9. Terminate SoundService by wring playSound(), which rst stops any sound

being played and then enqueue the new sound buer to play:

...

void SoundService::playSound(Sound* pSound) {

SLresult lRes;

SLuint32 lPlayerState;

(*mPlayerObj)->GetState(mPlayerObj, &lPlayerState);

if (lPlayerState == SL_OBJECT_STATE_REALIZED) {

int16_t* lBuffer = (int16_t*) pSound->mBuffer;

off_t lLength = pSound->mLength;

Playing Sound with OpenSL ES

[ 264 ]

// Removes any sound from the queue.

lRes = (*mPlayerQueue)->Clear(mPlayerQueue);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

// Plays the new sound.

lRes = (*mPlayerQueue)->Enqueue(mPlayerQueue, lBuffer,

lLength);

if (lRes != SL_RESULT_SUCCESS) goto ERROR;

}

return;

ERROR:

packt::Log::error(“Error trying to play sound”);

}

Let’s play a sound le when the game starts:

10. Store a reference to sound buer in le jni/DroidBlaster.hpp:

#ifndef _PACKT_DROIDBLASTER_HPP_

#define _PACKT_DROIDBLASTER_HPP_

#include “ActivityHandler.hpp”

#include “Background.hpp”

#include “Context.hpp”

#include “GraphicsService.hpp”

#include “Ship.hpp”

#include “Sound.hpp”

#include “SoundService.hpp”

#include “TimeService.hpp”

#include “Types.hpp”

namespace dbs {

class DroidBlaster : public packt::ActivityHandler {

...

private:

...

Background mBackground;

Ship mShip;

packt::Sound* mStartSound;

};

}

#endif

Chapter 7

[ 265 ]

11. Finally, play the sound in jni/DroidBlaster.cpp when the applicaon

is acvated:

#include “DroidBlaster.hpp”

#include “Log.hpp”

namespace dbs {

DroidBlaster::DroidBlaster(packt::Context* pContext) :

mGraphicsService(pContext->mGraphicsService),

mSoundService(pContext->mSoundService),

mTimeService(pContext->mTimeService),

mBackground(pContext), mShip(pContext),

mStartSound(mSoundService->registerSound(“start.pcm”))

{}

packt::status DroidBlaster::onActivate() {

...

mSoundService->playBGM(“bgm.mp3”);

mSoundService->playSound(mStartSound);

mBackground.spawn();

mShip.spawn();

...

}

What just happened?

We have discovered how to preload sounds in a buer and play them as needed. What

dierenates the sound playing technique from the BGM one showed earlier is the use of

a buer queue. A buer queue is exactly what its name reveals: a FIFO (First In, First Out)

collecon of sound buers played one aer the other. Buers are enqueued for playback

when all previous buers are played.

Buers can be recycled. This technique is essenal in combinaon with streaming les: two

or more buers are lled and sent to the queue. When rst buer has nished playing, the

second one starts while the rst buer is lled with new data. As soon as possible, the rst

buer is enqueued before the queue gets empty. This process repeats forever unl playback

is over. In addion, buers are raw data and can thus be processed or ltered on the y.

Playing Sound with OpenSL ES

[ 266 ]

In the present tutorial, because DroidBlaster does not need to play more than one sound

at once and no form of streaming is necessary, the buer queue size is simply set to one

buer (step 5, lDataLocatorIn.numBuffers = 1;). In addion, we want new sounds

to pre-empt older ones, which explains why queue is systemacally cleared. Your OpenSL

ES architecture should be of course adapted to your needs. If it becomes necessary to play

several sounds simultaneously, then several audio players (and therefore buer queues)

should be created.

Sound buers are stored in the PCM format, which does not self-describe its internal format.

Sampling, encoding, and other format informaon needs to be selected in the applicaon

code. Although this is ne for most of them, a soluon, if that is not exible enough, can be

to load a Wave le which contains all the necessary header informaon.

If you have read carefully the second part of this chapter about playing BGM, you will

remember that we have used a MIME data source to load dierent kind of sound les,

Waves included. So why not use a MIME source instead of a PCM source? Well, this is

because a buer queue works only with PCM data. Although improvements can be expected

in the future, audio le decoding sll need to be performed by hand. Trying to connect a

MIME source to a buer queue (like we are going to do with the recorder) will cause an

SL_RESULT_FEATURE_UNSUPPORTED error.

OpenSL ES has been updated in NDK R7 and now allows decoding

compressed les such as MP3 les to PCM buers.

Exporng PCM sounds with Audacity

A great open source tool to lter and sequence sounds is Audacity. It

allows altering sampling rate and modifying channels (Mono/Stereo).

Audacity is able to export as well as import sound as raw PCM data.

Event callback

It is possible to detect when a sound has nished playing using callbacks. A callback can be

set up by calling the RegisterCallback() method on a queue (but other type of objects

can also register callbacks) like in the following example:

...

namespace packt {

class SoundService {

...

Chapter 7

[ 267 ]

private:

static void callback_sound(SLBufferQueueItf pObject,

void* pContext);

...

};

}

#endif

For example, the callback can receive this, that is, a SoundService self reference, to allow

processing with any contextual informaon, if needed. Although this is facultave, an event

mask is set up to ensure callback is called only when event SL_PLAYEVENT_HEADATEND

(player has nished playing the buer) is triggered. A few others play events are available

in OpenSLES.h:

...

namespace packt {

...

status SoundService::startSoundPlayer() {

...

// Registers a callback called when sound is finished.

lResult = (*mPlayerQueue)->RegisterCallback(mPlayerQueue,

callback_sound, this);

slCheckErrorWithStatus(lResult, “Problem registering player

callback (Error %d).”, lResult);

lResult = (*mPlayer)->SetCallbackEventsMask(mPlayer, SL_

PLAYEVENT_HEADATEND);

slCheckErrorWithStatus(lResult, “Problem registering player

callback mask (Error %d).”, lResult);

// Starts the sound player

...

}

void callback_sound(SLBufferQueueItf pBufferQueue, void *context)

{

// Context can be casted back to the original type.

SoundService& lService = *(SoundService*) context;

...

Log::info(“Ended playing sound.”);

}

...

}

Playing Sound with OpenSL ES

[ 268 ]

Now, when a buer ends playing, a message is logged. Operaons like, for example,

enqueuing a new buer (to handle streaming for example) can be performed.

Callback and threading

Callbacks are like system interrupons or applicaon events:

their processing must be short and fast. If advanced processing

is necessary, it should not be performed inside the callback but

on another thread, nave threads being perfect candidates.

Indeed, callbacks are emied on a system thread, dierent than the one requesng OpenSL

ES services (that is, the nave thread in our case). Of course, with threads rise the problem

of thread-safety when accessing your own variables from the callback. Although protecng

code with mutexes is tempng, they are not always compable with real-me audio as their

eect on scheduling (inversion of priority issues) can disturb playback. Prefer using thread

safe technique like a lock-free queue to communicate with callbacks.

Recording sounds

Android devices are all about interacons. And interacons can come not only from touches

and sensors, but also from audio input. Most Android devices provide a micro to record

sound and allow an applicaon such as the Android desktop search to oer vocal features

to record queries.

If sound input is available, OpenSL ES gives access to the sound recorder navely. It

collaborates with a buer queue to take data from the input device and ll an output sound

buer from it. Setup is prey similar to what has been done with the AudioPlayer except

that data source and data sink are permuted.

To discover how this works, next the challenge consists in recording a sound when an

applicaon starts and playing it when it has nished recording.

Project DroidBlaster_Part7-3 can be used as a starng point for

this part. The resulng project is provided with this book under the

name DroidBlaster_Part7-Recorder.

Chapter 7

[ 269 ]

Have a go hero – recording and playing a sound

Turning SoundService into a recorder can be done in four steps:

1. Using status startSoundRecorder() inialize the sound recorder. Invoke it

right aer startSoundPlayer().

2. With void recordSound() start recording a sound buer with device micro.

Invoke this method at instances such as when the applicaon is acvated in

onActivate() aer background music playback starts.

3. A new callback static void callback_recorder(SLAndroidSimpleBuffe

rQueueItf, void*) to be noed of record queue events. You have to register

this callback so that it is triggered when a recorder event happens. Here, we are

interested in buer full events, that is, when the sound recording is nished.

4. void playRecordedSound() to play a sound once recorded. Play it at instances

such as when sound has nished being recorded in callback_recorder().

This is not technically correct because of potenal race condions but is ne for

an illustraon.

Before going any further, recording requires a specic authorizaon and, of course,

an appropriate Android device (you would not like an applicaon to record your

secret conversaons behind your back!). This authorizaon has to be requested in

Android manifest:

<?xml version=”1.0” encoding=”utf-8”?>

<manifest xmlns:android=”http://schemas.android.com/apk/res/android”

package=”com.packtpub.droidblaster” android:versionCode=”1”

android:versionName=”1.0”>

...

<uses-permission android:name=”android.permission.RECORD_AUDIO”/>

</manifest>

Sounds are recorded with a recorder object created from the OpenSL ES engine, as usual.

The recorder oers two interesng interfaces:

SLRecordItf: This interface is to start and stop recording. The idener is

SL_IID_RECORD.

SLAndroidSImpleBufferQueueItf: This manages a sound queue for the

recorder. This is an Android extension provided by NDK because current OpenSL

ES 1.0.1 specicaon does not support recording to a queue. The idener is

SL_IID_ANDROIDSIMPLEBUFFERQUEUE.

const SLuint32 lSoundRecorderIIDCount = 2;

const SLInterfaceID lSoundRecorderIIDs[] =

{ SL_IID_RECORD, SL_IID_ANDROIDSIMPLEBUFFERQUEUE };

Playing Sound with OpenSL ES

[ 270 ]

const SLboolean lSoundRecorderReqs[] =

{ SL_BOOLEAN_TRUE, SL_BOOLEAN_TRUE };

SLObjectItf mRecorderObj;

(*mEngine)->CreateAudioRecorder(mEngine, &mRecorderObj,

&lDataSource, &lDataSink,

lSoundRecorderIIDCount, lSoundRecorderIIDs,

lSoundRecorderReqs);

To create the recorder, you will need to declare your audio source and sink similar to the

following one. The data source is not a sound but a default recorder device (like a microphone).

On the other hand, the data sink (that is, the output channel) is not a speaker but a sound

buer in PCM format (with the requested sampling, encoding, and endianness). The Android

extension SLDataLocator_AndroidSimpleBufferQueue must be used to work with

a recorder since standard OpenSL buer queues cannot be used as with a recorder:

SLDataLocator_AndroidSimpleBufferQueue lDataLocatorOut;

lDataLocatorOut.locatorType =

SL_DATALOCATOR_ANDROIDSIMPLEBUFFERQUEUE;

lDataLocatorOut.numBuffers = 1;

SLDataFormat_PCM lDataFormat;

lDataFormat.formatType = SL_DATAFORMAT_PCM;

lDataFormat.numChannels = 1;

lDataFormat.samplesPerSec = SL_SAMPLINGRATE_44_1;

lDataFormat.bitsPerSample = SL_PCMSAMPLEFORMAT_FIXED_16;

lDataFormat.containerSize = SL_PCMSAMPLEFORMAT_FIXED_16;

lDataFormat.channelMask = SL_SPEAKER_FRONT_CENTER;

lDataFormat.endianness = SL_BYTEORDER_LITTLEENDIAN;

SLDataSink lDataSink;

lDataSink.pLocator = &lDataLocatorOut;

lDataSink.pFormat = &lDataFormat;

SLDataLocator_IODevice lDataLocatorIn;

lDataLocatorIn.locatorType = SL_DATALOCATOR_IODEVICE;

lDataLocatorIn.deviceType = SL_IODEVICE_AUDIOINPUT;

lDataLocatorIn.deviceID = SL_DEFAULTDEVICEID_AUDIOINPUT;

lDataLocatorIn.device = NULL;

SLDataSource lDataSource;

lDataSource.pLocator = &lDataLocatorIn;

lDataSource.pFormat = NULL;

Chapter 7

[ 271 ]

To record a sound, you also need to create a sound buer with an appropriate size according

to the duraon of your recording. Size depends on the sampling rate. For example, for a

record of 2 s with a sampling rate of 44100 Hz and 16-bit quality, sound buer size would

look like the following:

mRecordSize = 44100 * 2

mRecordBuffer = new int16_t[mRecordSize];

In recordSound(), you can stop the recorder thanks to SLRecordItf to ensure it is not

already recording and clear the queue. The same process applies to destroy the recorder

when applicaon exits.

(*mRecorder)->SetRecordState(mRecorder, SL_RECORDSTATE_STOPPED);

(*mRecorderQueue)->Clear(mRecorderQueue);

Then you can enqueue a new buer and start recording:

(*mRecorderQueue)->Enqueue(mRecorderQueue, mRecordBuffer,

mRecordSize * sizeof(int16_t));

(*mRecorder)->SetRecordState(mRecorder,SL_RECORDSTATE_RECORDING);

Of course, it would be perfectly possible to just enqueue a new sound so that any current

recording is processed to its end (for example, to create a connuous chain of recording).

The sound being enqueued would be processed potenally later in that case. All depends

on your needs.

You eventually need to know when your sound buer has nished recording. To do so,

lled). An event mask should be set to ensure callback is called only when a buer has been

lled (SL_RECORDEVENT_BUFFER_FULL). A few others are available in OpenSLES.h but

not all are supported (SL_RECORDEVENT_HEADATLIMIT, and so on):

(*mRecorderQueue)->RegisterCallback(mRecorderQueue,

callback_recorder, this);

(*mRecorder)->SetCallbackEventMask(mRecorder,

SL_RECORDEVENT_BUFFER_FULL);

Finally, when callback_recorder() is triggered, just stop recording and play the recorded

buer with playRecordedSound(). The recorded buer needs to be enqueued in the

audio player’s queue for playback:

(*mPlayerQueue)->Enqueue(mPlayerQueue, mRecordBuffer,

mRecordSize * sizeof(int16_t));

Playing Sound with OpenSL ES

[ 272 ]

Playing recorded sound directly from a callback is nice to perform quick

and simple tests. But to implement such a mechanism properly, more

advanced thread-safe technique (preferably lock-free) is required.

Indeed, in this example, there is a risk of race condion with SoundService destructor

(which destroys the queue used in the callback).

Summary

In this chapter, we saw how to create and realize an OpenSL ES engine connected to

an output channel. We played music from an encoded le and saw that an encoded le

cannot be loaded in a buer.

We also played sound buers in a sound queue. Buers can either be appended to a queue,

in which case they are played with delay, or inserted in replacement of previous sounds,

in which case they are played immediately. Finally, we have recorded sound in buers and

played them back.

Should you prefer OpenSL ES over Java APIs? There is no denite answer. Devices evolve

at much quieter pace than Android itself. So if your applicaon aims at a large compability,

that is, Android 2.2 or less, Java APIs are the only soluon. On the other hand, if it is planned

for later releases, then OpenSL ES is an opon to consider, praying that most devices will

be migrated to Gingerbread! But you have to be ready to support the cost of possible

future evoluons.

If all you need is a nice high-level API, then Java APIs may suit your requirements beer. If

you need ner playback or recording control, then there is no signicant dierence between

low-level Java APIs and OpenSL ES. In that case, choice should be architectural: if your code

is mainly Java, then you should probably go with Java and reciprocally. If you need to reuse

an exisng sound-related library, opmize performance or perform intense computaons,

like sound ltering on the y, then OpenSL ES is probably the right choice. There is no

garbage collector overhead and aggressive opmizaon is favored in the nave code.

Whatever choice you make, know that Android NDK has a lot more to oer. Aer rendering

graphics with Open GL ES and playing sound with OpenSL ES, the next chapter will take care

of handling input navely: keyboard, touches, and sensors.

Handling Input Devices and Sensors

Android is all about interacon. Admiedly, that means feedback, through

graphics, audio, vibraons, and so on. But there is no interacon without input!

The success of today's smart-phones takes its root in their mulple and modern

input possibilies: touch screens, keyboard, mouse, GPS, accelerometer, light

detector, sound recorder, and so on. Handling and combining them properly is a

key to enrich your applicaon and and to make it successful.

Although Android handles many input peripherals, the Android NDK has long been very

limited in their support, not to say good for nothing, unl the release of R5! We can now

access them directly through a nave API. Examples of available devices are:

Keyboard, either physical (with a slide-out keyboard) or virtual (which appears

on screen)

Direconal pad (up, down, le, right, and acon buons), oen

abbreviated D-Pad

Trackball (opcal ones included)

Touch screen, which has made the success of modern smart-phones

Mouse or Track Pad (since NDK R5, but available on Honeycomb devices only)

We can also access hardware sensors, for example:

Accelerometer, which measures linear acceleraon applied to a device.

Gyroscope, which measures angular velocity. It is oen combined with the

magnetometer to compute orientaon accurately and quickly. Gyroscope has

been introduced recently and is not available on most devices yet.

Handling Input Devices and Sensors

[ 274 ]

Magnetometer, which gives the ambient magnec eld and thus (if not perturbed)

cardinal direcon.

Light sensor, for example, to automacally adapt screen luminosity.

Proximity sensor, for example, to detect ear distance during a call.

In addion to hardware sensors, "soware sensors" have been introduced with Gingerbread.

These sensors are derived from hardware sensor's data:

Gravity sensor, to measure the gravity direcon and magnitude

Linear acceleraon sensor, which measures device "movement" excluding gravity

Rotaon vector, which indicates device orientaon in space

Gravity sensor and linear acceleraon sensor are derived from the accelerometer. On the

other hand, rotaon vector is derived from the magnetometer and the accelerometer.

Because these sensors are generally computed over me, they usually incur a slight delay

to get up-to-date values.

To familiarize more deeply with input devices and sensors, this chapter teaches how to:

Handle screen touches

Detect keyboard, D-Pad, and trackball events

Turn the accelerometer sensor into a joypad

Interacting with Android

The most emblemac innovaon of today's smart phones is the touch screen, which has

replaced the now anque mice. A touch screen detects, as its name suggests, touches

made with ngers or styluses. Depending on the quality of the screen, several touches

(also referred as cursors in Android) can be handled, de-mulplying interacon possibilies.

So let's start this chapter by handling touch events in DroidBlaster. To keep the example

simple, we will only handle one touch. The goal is to move the ship in the direcon of a

touch. The farther the touch is, the faster goes the ship. Beyond a pre-dened range, ship

speed reaches a top limit.

Chapter 8

[ 275 ]

The nal project structure will look as shown in the following diagram:

DroidBlaster

Ship

LogContext

TimeService

GraphicsService

EventLoop

GraphicsTexture Resource

packt

ActivityHandler

Background

GraphicsTileMap

GraphicsSprite Location

dbsdbs

RapidXml

SoundService

InputService

*Sound

InputHandler

Project DroidBlaster_Part7-3 can be used as a starng

point for this part. The resulng project is provided with this

book under the name DroidBlaster_Part8-1.

Handling Input Devices and Sensors

[ 276 ]

Time for action – handling touch events

Let's begin with the plumber to connect Android input event queue to our applicaon.

1. In the same way we created an ActivityHandler to process applicaon events

in Chapter 5, Wring a Nave Applicaon, create a class InputHandler, in a new

le jni/InputHandler.hpp to process the input events. Input API is declared in

android/input.h.

2. Create a onTouchEvent() to handle touch events. These events are packaged in

an AInputEvent structure dened in Android include les. Other input peripherals

will be added later in this chapter:

#ifndef _PACKT_INPUTHANDLER_HPP_

#define _PACKT_INPUTHANDLER_HPP_

#include <android/input.h>

namespace packt {

class InputHandler {

public:

virtual ~InputHandler() {};

virtual bool onTouchEvent(AInputEvent* pEvent) = 0;

};

}

#endif

3. Modify jni/EventLoop.hpp header le to include and handle an

InputHandler instance. Like with acvity event, dene an internal method

processInputEvent() triggering a stac callback callback_input():

#ifndef _PACKT_EVENTLOOP_HPP_

#define _PACKT_EVENTLOOP_HPP_

#include "ActivityHandler.hpp"

#include "InputHandler.hpp"

#include "Types.hpp"

#include <android_native_app_glue.h>

namespace packt {

class EventLoop {

public:

EventLoop(android_app* pApplication);

Chapter 8

[ 277 ]

void run(ActivityHandler* pActivityHandler,

InputHandler* pInputHandler);

protected:

...

void processAppEvent(int32_t pCommand);

int32_t processInputEvent(AInputEvent* pEvent);

void processSensorEvent();

private:

...

static void callback_event(android_app* pApplication,

int32_t pCommand);

static int32_t callback_input(android_app* pApplication,

AInputEvent* pEvent);

private:

...

android_app* mApplication;

ActivityHandler* mActivityHandler;

InputHandler* mInputHandler;

};

}

#endif

4. We need to process input events in jni/EventLoop.cpp source le and nofy

the associated InputHandler.

First, connect the Android input queue to our callback_input(). The

EventLoop itself (that is, this) is passed anonymously through the userData

member of the android_app structure. That way, callback is able to delegate

input processing back to our own object, that is, to processInputEvent().

Touch screen events are of the type MotionEvent (as opposed to key events). They

can be discriminated according to their source (AINPUT_SOURCE_TOUCHSCREEN)

thanks to Android nave input API (here, AInputEvent_getSource()):

Note how callback_input() and by extension processInputEvent()

return an integer value (which is in fact a Boolean). This value indicates that

an input event (for example, a pressed buon) has been processed by the

applicaon and does not need to be processed further by the system. For

example, return 1 when the back buon is pressed to stop event processing and

prevent acvity from geng terminated.

Handling Input Devices and Sensors

[ 278 ]

#include "EventLoop.hpp"

#include "Log.hpp"

namespace packt {

EventLoop::EventLoop(android_app* pApplication) :

mEnabled(false), mQuit(false),

mApplication(pApplication),

mActivityHandler(NULL), mInputHandler(NULL) {

mApplication->userData = this;

mApplication->onAppCmd = callback_event;

mApplication->onInputEvent = callback_input;

}

void EventLoop::run(ActivityHandler* pActivityHandler,

InputHandler* pInputHandler) {

int32_t lResult;

int32_t lEvents;

android_poll_source* lSource;

// Makes sure native glue is not stripped by the linker.

app_dummy();

mActivityHandler = pActivityHandler;

mInputHandler = pInputHandler;

packt::Log::info("Starting event loop");

while (true) {

// Event processing loop.

...

}

...

int32_t EventLoop::processInputEvent(AInputEvent* pEvent) {

int32_t lEventType = AInputEvent_getType(pEvent);

switch (lEventType) {

case AINPUT_EVENT_TYPE_MOTION:

switch (AInputEvent_getSource(pEvent)) {

case AINPUT_SOURCE_TOUCHSCREEN:

return mInputHandler->onTouchEvent(pEvent);

break;

}

break;

}

Chapter 8

[ 279 ]

return 0;

}

int32_t EventLoop::callback_input(android_app* pApplication,

AInputEvent* pEvent) {

EventLoop& lEventLoop = *(EventLoop*) pApplication->userData;

return lEventLoop.processInputEvent(pEvent);

}

Plumber is ready. Let's handle these events concretely.

5. To analyze touch events, create a InputService class in jni/InputService.

hpp implemenng our InputHandler. It contains a start() method to realize

necessary inializaons and implements onTouchEvent().

More interesngly, InputService provides getHorizontal() and

getVertical() methods, which indicate the virtual joypad direcon. Direcon

is dened between the touch point and a reference point (which will be the ship).

We also need to know window height and width (reference values, which come

from GraphicsService) to handle coordinate conversions:

#ifndef _PACKT_INPUTSERVICE_HPP_

#define _PACKT_INPUTSERVICE_HPP_

#include "Context.hpp"

#include "InputHandler.hpp"

#include "Types.hpp"

#include <android_native_app_glue.h>

namespace packt {

class InputService : public InputHandler {

public:

InputService(android_app* pApplication,

const int32_t& pWidth, const int32_t& pHeight);

float getHorizontal();

float getVertical();

void setRefPoint(Location* pTouchReference);

status start();

public:

Handling Input Devices and Sensors

[ 280 ]

bool onTouchEvent(AInputEvent* pEvent);

private:

android_app* mApplication;

float mHorizontal, mVertical;

Location* mRefPoint;

const int32_t& mWidth, &mHeight;

};

}

#endif

6. Now, the interesng part: jni/InputService.cpp. First, dene the constructor,

destructor, geers, and seers.

Input service needs a start() method to clear state members:

#include "InputService.hpp"

#include "Log.hpp"

#include <android_native_app_glue.h>

#include <cmath>

namespace packt {

InputService::InputService(android_app* pApplication,

const int32_t& pWidth, const int32_t& pHeight) :

mApplication(pApplication),

mHorizontal(0.0f), mVertical(0.0f),

mRefPoint(NULL), mWidth(pWidth), mHeight(pHeight)

{}

float InputService::getHorizontal() {

return mHorizontal;

}

float InputService::getVertical() {

return mVertical;

}

void InputService::setRefPoint(Location* pTouchReference) {

mRefPoint = pTouchReference;

}

status InputService::start() {

Chapter 8

[ 281 ]

mHorizontal = 0.0f, mVertical = 0.0f;

if ((mWidth == 0) || (mHeight == 0)) {

return STATUS_KO;

}

return STATUS_OK;

}

The eecve event processing comes in onTouchEvent(). Horizontal and vercal

direcons are computed according to the distance between the reference point and

the touch point. This distance is restricted by TOUCH_MAX_RANGE to an arbitrary

range of 65 pixels. Thus, ship max speed is reached when reference-to-touch point

distance is beyond TOUCH_MAX_RANGE pixels. Touch coordinates are retrieved

thanks to AMotionEvent_getX() and AMotionEvent_getY() when nger

moves. Direcon vector is reset to 0 when no more touch is detected:

Beware that the way touch events are red is not homogeneous among

devices. For example, some devices emit events connuously while

nger is down whereas others only emit them when nger moves. In

our case, we could re-compute movement each frame instead of when

an event is triggered to get a more predictable behavior.

...

bool InputService::onTouchEvent(AInputEvent* pEvent) {

const float TOUCH_MAX_RANGE = 65.0f; // In pixels.

if (mRefPoint != NULL) {

if (AMotionEvent_getAction(pEvent)

== AMOTION_EVENT_ACTION_MOVE) {

// Needs a conversion to proper coordinates

// (origin at bottom/left). Only lMoveY needs it.

float lMoveX = AMotionEvent_getX(pEvent, 0)

- mRefPoint->mPosX;

float lMoveY = mHeight - AMotionEvent_getY(pEvent, 0)

- mRefPoint->mPosY;

float lMoveRange = sqrt((lMoveX * lMoveX)

+ (lMoveY * lMoveY));

if (lMoveRange > TOUCH_MAX_RANGE) {

float lCropFactor = TOUCH_MAX_RANGE / lMoveRange;

lMoveX *= lCropFactor; lMoveY *= lCropFactor;

}

mHorizontal = lMoveX / TOUCH_MAX_RANGE;

Handling Input Devices and Sensors

[ 282 ]

mVertical = lMoveY / TOUCH_MAX_RANGE;

} else {

mHorizontal = 0.0f; mVertical = 0.0f;

}

return true;

}

7. Insert InputService into the Context structure in jni/Context.hpp.

#ifndef _PACKT_CONTEXT_HPP_

#define _PACKT_CONTEXT_HPP_

#include "Types.hpp"

namespace packt {

class GraphicsService;

class InputService;

class SoundService;

class TimeService;

struct Context {

GraphicsService* mGraphicsService;

InputService* mInputService;

SoundService* mSoundService;

TimeService* mTimeService;

};

}

#endif

Finally, let's react to touch events in the game itself.

8. Get the InputService back in jni/DroidBlaster.hpp:

#ifndef _PACKT_DROIDBLASTER_HPP_

#define _PACKT_DROIDBLASTER_HPP_

#include "ActivityHandler.hpp"

#include "Background.hpp"

#include "Context.hpp"

#include "InputService.hpp"

#include "GraphicsService.hpp"

#include "Ship.hpp"

...

Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >

Chapter 8

[ 283 ]

namespace dbs {

class DroidBlaster : public packt::ActivityHandler {

public:

...

private:

packt::InputService* mInputService;

packt::GraphicsService* mGraphicsService;

packt::SoundService* mSoundService;

packt::TimeService* mTimeService;

...

};

}

#endif

9. InputService is started in jni/DroidBlaster.cpp when the acvity is

acvated. Because it calls ANativeWindow_lock() to retrieve window height

and width, InputService needs to be started before GraphicsService to

avoid a deadlock:

#include "DroidBlaster.hpp"

#include "Log.hpp"

namespace dbs {

DroidBlaster::DroidBlaster(packt::Context* pContext) :

mInputService(pContext->mInputService),

mGraphicsService(pContext->mGraphicsService),

mSoundService(pContext->mSoundService),

...

{}

packt::status DroidBlaster::onActivate() {

if (mGraphicsService->start() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

if (mInputService->start() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

...

}

...

packt::status DroidBlaster::onStep() {

Handling Input Devices and Sensors

[ 284 ]

mTimeService->update();

mBackground.update();

mShip.update();

// Updates services.

if (mGraphicsService->update() != packt::STATUS_OK) {

...

}

10. The InputService is used by the Ship class to reposion. Open jni/Ship.hpp

and associate it with the InputService and TimeService. The ship posion is

moved according to user input and me step in a new method update():

#ifndef _DBS_SHIP_HPP_

#define _DBS_SHIP_HPP_

#include "Context.hpp"

#include "InputService.hpp"

#include "GraphicsService.hpp"

#include "GraphicsSprite.hpp"

#include "Types.hpp"

namespace dbs {

class Ship {

public:

Ship(packt::Context* pContext);

void spawn();

void update();

private:

packt::InputService* mInputService;

packt::GraphicsService* mGraphicsService;

packt::TimeService* mTimeService;

packt::GraphicsSprite* mSprite;

packt::Location mLocation;

float mAnimSpeed;

};

}

#endif

Chapter 8

[ 285 ]

11. The reference point from which distance to the touch is computed is inialized with

the ship posion. During update, ship is moved toward the touch point according to

the me step and the direcon calculated in InputService class:

#include "Ship.hpp"

#include "Log.hpp"

namespace dbs {

Ship::Ship(packt::Context* pContext) :

mInputService(pContext->mInputService),

mGraphicsService(pContext->mGraphicsService),

mTimeService(pContext->mTimeService),

mLocation(), mAnimSpeed(8.0f) {

mSprite = pContext->mGraphicsService->registerSprite(

mGraphicsService->registerTexture("ship.png"), 64, 64,

&mLocation);

mInputService->setRefPoint(&mLocation);

}

...

void Ship::update() {

const float SPEED_PERSEC = 400.0f;

float lSpeed = SPEED_PERSEC * mTimeService->elapsed();

mLocation.translate(mInputService->getHorizontal() * lSpeed,

mInputService->getVertical() * lSpeed);

}

12. Finally, update the android_main() method in jni/Main.cpp to build

an instance of InputService and pass it to the event processing loop:

#include "Context.hpp"

#include "DroidBlaster.hpp"

#include "EventLoop.hpp"

#include "InputService.hpp"

#include "GraphicsService.hpp"

#include "SoundService.hpp"

#include "TimeService.hpp"

void android_main(android_app* pApplication) {

packt::TimeService lTimeService;

packt::GraphicsService lGraphicsService(pApplication,

&lTimeService);

Handling Input Devices and Sensors

[ 286 ]

packt::InputService lInputService(pApplication,

lGraphicsService.getWidth(),lGraphicsService.getHeight());

packt::SoundService lSoundService(pApplication);

packt::Context lContext = { &lInputService, &lGraphicsService,

&lSoundService, &lTimeService };

packt::EventLoop lEventLoop(pApplication);

dbs::DroidBlaster lDroidBlaster(&lContext);

lEventLoop.run(&lDroidBlaster, &lInputService);

}

What just happened?

We have created a simple example of an input system based on touch events. The ship

ies toward the touch point at a speed dependent on the touch distance. Yet, many

improvements are possible such as taking into account screen density and size, following

one specic pointer…

Touch screen event coordinates are absolute. Their origin is in the upper-le corner of the

screen (on the opposite of OpenGL which is on the lower-le corner). If screen rotaon is

authorized by an applicaon, the origin will stay on the upper, le whether the screen is in

portrait or landscape mode.

To implement it, we have connected our event loop to the input event queue provided

by the native_app_glue module. This queue is internally represented as an Unix pipe,

like the acvity event queue. Touch screen events are embedded in an AInputEvent

structure, which stores also other kind of input events. Input events can be handled with

the funcons declared in android/input.h. Input event types can be discriminated

using AInputEvent_getType() and AInputEvent_getSource() methods (note the

AInputEvent_ prex). Methods related to touch events are prexed by AMotionEvent_.

Chapter 8

[ 287 ]

The touch API is rather rich. Many details can be requested such as (non-exhausvely):

AMotionEvent_getAction() To detect whether a nger is entering in contact with

the screen, leaving it, or moving over the surface.

The result is an integer value composed of the event

type (on byte 1, for example, AMOTION_EVENT_

ACTION_DOWN) and a pointer index (on byte 2, to

know which nger the event refers to).

AMotionEvent_getX()

AMotionEvent_getY()

To retrieve touch coordinates on screen, expressed in

pixels as a oat (sub-pixel values are possible).

AMotionEvent_getDownTime()

AMotionEvent_getEventTime()

To retrieve how much me nger has been sliding

over the screen and when the event has been

generated in nanoseconds.

AMotionEvent_getPressure()

AMotionEvent_getSize()

To detect how careful users are with their device.

Values usually range between 0.0 and 1.0 (but may

exceed it). Size and pressure are generally closely

related. Behavior can vary greatly and be noisy

depending on hardware.

AMotionEvent_

getHistorySize()

AMotionEvent_

getHistoricalX()

AMotionEvent_

getHistoricalY()

...

Touch events of type AMOTION_EVENT_ACTION_

MOVE can be grouped together for eciency purpose.

These methods give access to these "historical points"

that occurred between previous and current events.

Have a look at android/input.h for an exhausve list of methods.

If you look more deeply at AMotionEvent API, you will noce that some events have a

second parameter pointer_index, which ranges between 0 and the number of acve

pointers. Indeed, most touch screens today are mul-touch! Two or more ngers on a screen

(if hardware supports it) are translated in Android by two or more pointers. To manipulate

them, look at:

AMotionEvent_

getPointerCount()

To know how many ngers touch the screen.

AMotionEvent_getPointerId() To get a pointer unique idener from a pointer

index. This is the only way to track a parcular

pointer (that is, nger) over me, as its index may

change when ngers touch or leave the screen.

Handling Input Devices and Sensors

[ 288 ]

Do not rely on hardware

If you followed the story of the (now prehistoric!) Nexus One, then you know

that it came out with an hardware defect. Pointers were oen geng mixed

up, two of them exchanging one of their coordinates. So be always prepared

to handle hardware specicies or hardware that behaves incorrectly!

Detecting keyboard, D-Pad, and Trackball events

The most common input device among all is the keyboard. This is true for Android too. An

Android keyboard can be physical: in the device front face (like tradional blackberries) or

on a slide-out screen. But a keyboard can also be virtual, that is, emulated on the screen at

the cost of a large poron of space taken. In addion to the keyboard itself, every Android

device should include a few physical buons (somemes emulated on screen) such as Menu,

Home, Search, and so on.

A much less common type of input device is the Direconal-Pad. A D-Pad is a set of physical

buons to move up, down, le, or right and a specic acon/conrmaon buon. Although

they oen disappear from recent phones and tablets, D-Pads remain one of the most

convenient ways to move across text or UI widgets. D-Pads are oen replaced by trackballs.

Trackballs behave similarly to a mouse (the one with a ball inside) that would be upside-down.

Some trackballs are analogical, but others (for example, opcal ones) behave as a D-Pad

(that is, all or nothing).

To see how they work, let's use these peripherals to move our space ship in DroidBlaster.

The Android NDK now allows handling all these input peripherals on the nave side. So let's

try them!

Chapter 8

[ 289 ]

Project DroidBlaster_Part8-1 can be used as a starng

point for this part. The resulng project is provided with this

book under the name DroidBlaster_Part8-2.

Time for action – handling keyboard, D-Pad, and

trackball, natively

First, let's handle keyboard and trackball events.

1. Open jni/InputHandler.hpp and add keyboard and trackball event handlers:

#ifndef _PACKT_INPUTHANDLER_HPP_

#define _PACKT_INPUTHANDLER_HPP_

#include <android/input.h>

namespace packt {

class InputHandler {

public:

virtual ~InputHandler() {};

virtual bool onTouchEvent(AInputEvent* pEvent) = 0;

virtual bool onKeyboardEvent(AInputEvent* pEvent) = 0;

virtual bool onTrackballEvent(AInputEvent* pEvent) = 0;

};

}

#endif

2. Update method processInputEvent() inside the exisng le jni/EventLoop.

cpp to redirect keyboard and trackball events to InputHandler.

Trackballs and touch events are assimilated to moon events and can be

discriminated according to their source. On the opposite side, key events are

discriminated according to their type. Indeed, there exist two dedicated APIs for

MotionEvents (the same for trackballs and touch events) and for KeyEvents

(idencal for keyboard, D-Pad, and so on):

#include "EventLoop.hpp"

#include "Log.hpp"

namespace packt {

...

int32_t EventLoop::processInputEvent(AInputEvent* pEvent) {

Handling Input Devices and Sensors

[ 290 ]

int32_t lEventType = AInputEvent_getType(pEvent);

switch (lEventType) {

case AINPUT_EVENT_TYPE_MOTION:

switch (AInputEvent_getSource(pEvent)) {

case AINPUT_SOURCE_TOUCHSCREEN:

return mInputHandler->onTouchEvent(pEvent);

break;

case AINPUT_SOURCE_TRACKBALL:

return mInputHandler->onTrackballEvent(pEvent);

break;

}

break;

case AINPUT_EVENT_TYPE_KEY:

return mInputHandler->onKeyboardEvent(pEvent);

break;

}

return 0;

}

...

}

3. Now, modify the jni/InputService.hpp le to override these new methods…

also dene an update() method to react to pressed keys. We are interested in

the menu buon that is going to cause the applicaon to exit:

#ifndef _PACKT_INPUTSERVICE_HPP_

#define _PACKT_INPUTSERVICE_HPP_

...

namespace packt {

class InputService : public InputHandler {

public:

...

status start();

status update();

public:

bool onTouchEvent(AInputEvent* pEvent);

bool onKeyboardEvent(AInputEvent* pEvent);

bool onTrackballEvent(AInputEvent* pEvent);

Chapter 8

[ 291 ]

private:

...

Location* mRefPoint;

int32_t mWidth, mHeight;

bool mMenuKey;

};

}

#endif

4. Now, update the class constructor jni/InputService.cpp and implement

method update() to exit when the menu buon is pressed:

#include "InputService.hpp"

#include "Log.hpp"

#include <android_native_app_glue.h>

#include <cmath>

namespace packt {

InputService::InputService(android_app* pApplication,

const int32_t& pWidth, const int32_t& pHeight) :

mApplication(pApplication),

mHorizontal(0.0f), mVertical(0.0f),

mRefPoint(NULL), mWidth(pWidth), mHeight(pHeight),

mMenuKey(false)

{}

...

status InputService::update() {

if (mMenuKey) {

return STATUS_EXIT;

}

return STATUS_OK;

}

...

5. Sll in InputService.cpp, process keyboard events in onKeyboardEvent(). Use:

AKeyEvent_getAction() to get event type (that is, pressed or not).

AKeyEvent_getKeyCode() to get the buon identy.

Handling Input Devices and Sensors

[ 292 ]

In the following code, when le, right, up, or down buons are pressed,

InputService compute corresponding direcon into elds mHorizontal

and mVertical dened in previous part. Movement starts when buon is

down and stops when it is up.

We also process the Menu buon here, when it gets unpressed:

This code works only on devices with a D-Pad, which is the

case of the emulator. Note however that due to Android

fragmentaon, reacon may dier according to hardware.

...

bool InputService::onKeyboardEvent(AInputEvent* pEvent) {

const float ORTHOGONAL_MOVE = 1.0f;

if(AKeyEvent_getAction(pEvent)== AKEY_EVENT_ACTION_DOWN) {

switch (AKeyEvent_getKeyCode(pEvent)) {

case AKEYCODE_DPAD_LEFT:

mHorizontal = -ORTHOGONAL_MOVE;

break;

case AKEYCODE_DPAD_RIGHT:

mHorizontal = ORTHOGONAL_MOVE;

break;

case AKEYCODE_DPAD_DOWN:

mVertical = -ORTHOGONAL_MOVE;

break;

case AKEYCODE_DPAD_UP:

mVertical = ORTHOGONAL_MOVE;

break;

case AKEYCODE_BACK:

return false;

}

} else {

switch (AKeyEvent_getKeyCode(pEvent)) {

case AKEYCODE_DPAD_LEFT:

case AKEYCODE_DPAD_RIGHT:

mHorizontal = 0.0f;

break;

case AKEYCODE_DPAD_DOWN:

case AKEYCODE_DPAD_UP:

mVertical = 0.0f;

break;

case AKEYCODE_MENU:

Chapter 8

[ 293 ]

mMenuKey = true;

break;

case AKEYCODE_BACK:

return false;

}

return true;

}

...

6. Similarly, process trackball events in a new method onTrackballEvent(). Retrieve

trackball magnitude with AMotionEvent_getX() and AMotionEvent_getY().

Because some trackballs do not oer a gradated magnitude, the movement is

quaned with plain constants. Possible noise is ignored with an arbitrary

trigger threshold:

When using trackball that way, the ship moves unl a "counter-movement"

(for example, requesng to go to the right when going le) or acon buon

is pressed (last else secon):

For a wide audience applicaon, code should be adapted

to handle hardware capabilies and specicies such as

gradated values of analogical trackballs.

...

bool InputService::onTrackballEvent(AInputEvent* pEvent) {

const float ORTHOGONAL_MOVE = 1.0f;

const float DIAGONAL_MOVE = 0.707f;

const float THRESHOLD = (1/100.0f);

if (AMotionEvent_getAction(pEvent)

== AMOTION_EVENT_ACTION_MOVE) {

float lDirectionX = AMotionEvent_getX(pEvent, 0);

float lDirectionY = AMotionEvent_getY(pEvent, 0);

float lHorizontal, lVertical;

if (lDirectionX < -THRESHOLD) {

if (lDirectionY < -THRESHOLD) {

lHorizontal = -DIAGONAL_MOVE;

lVertical = DIAGONAL_MOVE;

} else if (lDirectionY > THRESHOLD) {

lHorizontal = -DIAGONAL_MOVE;

lVertical = -DIAGONAL_MOVE;

Handling Input Devices and Sensors

[ 294 ]

} else {

lHorizontal = -ORTHOGONAL_MOVE;

lVertical = 0.0f;

}

} else if (lDirectionX > THRESHOLD) {

if (lDirectionY < -THRESHOLD) {

lHorizontal = DIAGONAL_MOVE;

lVertical = DIAGONAL_MOVE;

} else if (lDirectionY > THRESHOLD) {

lHorizontal = DIAGONAL_MOVE;

lVertical = -DIAGONAL_MOVE;

} else {

lHorizontal = ORTHOGONAL_MOVE;

lVertical = 0.0f;

}

} else if (lDirectionY < -THRESHOLD) {

lHorizontal = 0.0f;

lVertical = ORTHOGONAL_MOVE;

} else if (lDirectionY > THRESHOLD) {

lHorizontal = 0.0f;

lVertical = -ORTHOGONAL_MOVE;

}

// Ends movement if there is a counter movement.

if ((lHorizontal < 0.0f) && (mHorizontal > 0.0f)) {

mHorizontal = 0.0f;

} else if((lHorizontal > 0.0f)&&(mHorizontal < 0.0f)){

mHorizontal = 0.0f;

} else {

mHorizontal = lHorizontal;

}

if ((lVertical < 0.0f) && (mVertical > 0.0f)) {

mVertical = 0.0f;

} else if ((lVertical > 0.0f) && (mVertical < 0.0f)) {

mVertical = 0.0f;

} else {

mVertical = lVertical;

}

} else {

mHorizontal = 0.0f; mVertical = 0.0f;

}

return true;

}

Let's nish by making a slight modicaon to the game itself.

Chapter 8

[ 295 ]

7. Finally, edit DroidBlaster.cpp and update InputService at each iteraon:

#include "DroidBlaster.hpp"

#include "Log.hpp"

namespace dbs {

...

packt::status DroidBlaster::onStep() {

mTimeService->update();

mBackground.update();

mShip.update();

if (mInputService->update() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

if (mGraphicsService->update() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

return packt::STATUS_OK;

}

...

}

What just happened?

We have extended our input system to handle the keyboard, D-Pad, and trackball events.

D-Pad can be considered as a keyboard extension and is processed the same way. Indeed,

D-Pad and keyboard events are transported in the same structure (AInputEvent) and

handled by the same API (prexed with AKeyEvent). The following table lists the main key

event methods:

Handling Input Devices and Sensors

[ 296 ]

AKeyEvent_getAction() Indicate if buon is down (AKEY_EVENT_ACTION_

DOWN) or released (AKEY_EVENT_ACTION_UP). Note

that mulple key acons can be emied in batch (AKEY_

EVENT_ACTION_MULTIPLE).

AKeyEvent_getKeyCode() To retrieve the actual buon being pressed (dened in

android/keycodes.h), for example, AKEYCODE_

DPAD_LEFT for the le buon.

AKeyEvent_getFlags() Key events can be associated with one or more ags

that give various informaon on the event like AKEY_

EVENT_LONG_PRESS, AKEY_EVENT_FLAG_SOFT_

KEYBOARD for event originated from an emulated

keyboard.

AKeyEvent_getScanCode() Is similar to a key code except that this is the raw key ID,

dependent and dierent from device to device.

AKeyEvent_getMetaState() Meta states are ags that indicate if some modier keys

like Alt or Shi are pressed simultaneously (for example,

AMETA_SHIFT_ON, AMETA_NONE, and so on).

AKeyEvent_

getRepeatCount()

Indicates how many mes the buon event occurred,

usually when you leave buon down.

AKeyEvent_getDownTime() To know when a buon was pressed.

Although some of them (especially opcal ones) behave like a D-Pad, trackballs are not using

the same API. Actually, trackballs are handled through the AMotionEvent API (like touch

events). Of course, some informaon provided for touch events is not always available on

trackballs. The most important funcons to look at are:

AMotionEvent_getAction() To know if an event represents a move acon (as opposed

to a press acon).

AMotionEvent_getX()

AMotionEvent_getY()

To get trackball movement.

AKeyEvent_getDownTime() To know if trackball is pressed (like D-Pad acon buon).

Currently, most trackballs use an all-or-nothing pressure

to indicate the press event.

Something tricky with trackballs, that may not be obvious at rst, is that no event up is

generated to indicate that trackball has nished moving. Moreover, trackball events are

generated as a series (as a burst) which makes it harder to detect when movement is

nished. There is no easy way to handle this except using a manual mer and checking

regularly that no event has happened for a sucient amount of me.

Chapter 8

[ 297 ]

Again, do not rely on an expected behaviour

Never expect peripherals to behave exactly the same on all phones.

Trackballs are a very good example: they can either indicate a direcon like

an analogical pad or a straight direcon like a D-Pad (for example, opcal

trackballs). There is currently no way to dierenate device characteriscs

from the available APIs. The only soluons are to either calibrate device

and congure it at runme or save a kind of device database.

Have a go hero – displaying software keyboard

An annoying problem with the Android NDK and NativeActivity is that there is no easy

way to display a virtual keyboard. And of course, without a virtual keyboard, nothing can

be keyed in. This is where the JNI skills you have gained by reading Chapter 3 and Chapter 4

come to the rescue.

The piece of Java code to show or hide the keyboard is rather concise:

InputMethodManager mgr = (InputMethodManager)

myActivity.getSystemService(Context.INPUT_METHOD_SERVICE);

mgr.showSoftInput(pActivity.getWindow().getDecorView(), 0);

...

mgr.hideSoftInput(pActivity.getWindow().getDecorView(), 0);

Write the equivalent JNI code in four steps:

1. First, create a JNI helper class which:

Takes an android_app instance and aaches the JavaVM during

construcon. The JavaVM is provided in member activity->vm

of android_app.

Detaches the JavaVM when class gets destroyed.

Oers helper methods to create and delete global references like

implemented in Chapter 4, Calling Back Java from Nave Code

(makeGlobalRef() and deleteGlobalRef()).

Provides geers to a JNIEnv cached on VM aachment and the

NativeActivity instance provided in member activity->clazz

of android_app.

Handling Input Devices and Sensors

[ 298 ]

2. Then, write a Keyboard class which receives a JNI instance in parameter and cache

all the necessary jclass, jmethodID, and jfieldID to execute the piece of Java

code presented above. This is similar to the StoreWatcher in Chapter 4, Calling

Back Java from Nave Code, but in C++ this me.

Dene methods to:

Cache JNI elements. Call it when InputService is inialized to handle

error cases properly and report a status.

Release global references when applicaon is deacvated.

Show and hide the keyboard by execung the JNI methods cached earlier.

3. Instanate both the JNI and the Keyboard classes in your android_main()

method and pass the laer to your InputService.

4. Open the virtual keyboard when the menu key is pressed instead of leaving the

game. Finally, detect keys that are pressed on the virtual keyboard. For example,

try to detect the key AKEYCODE_E to exit the game.

The nal project is provided with this book in

DroidBlaster_Part8-2-Keyboard.

Probing device sensors

Handling input devices is essenal to any applicaon, but probing sensors is important

for the smartest one! The most spread sensor among Android game applicaons is

the accelerometer.

An accelerometer, as its name suggests, measures the linear acceleraon applied to a

device. When moving a device up, down, le, or right, the accelerometer gets excited and

indicates an acceleraon vector in 3D space. Vector is expressed relave to screen default

orientaon. Coordinates system is relave to device natural orientaon:

X axis points le

Y points up

Z points from back to front

Axes become inverted if device is rotated (for example, Y points le if the device is rotated

90 degrees clockwise).

Chapter 8

[ 299 ]

A very interesng feature of accelerometers is that they undergo a constant acceleraon:

gravity, around 9.8m/s2 on earth. For example, when lying at on a table, acceleraon vector

indicates -9.8 on the Z-axis. When straight, it indicates the same value on Y axis. So assuming

device posion is xed, device orientaon on two axes in space can be deduced from the

gravity acceleraon vector. Magnetometer is sll required to get full device orientaon in

3D space.

Remember that accelerometers work with linear acceleraon.

They allow detecng translaon when device is not rotang and

paral orientaon when device is xed. But both movements

cannot be combined without a magnetometer and/or gyroscope.

The nal project structure will look as shown in the following diagram:

DroidBlaster

Ship

LogContext

TimeService

GraphicsService

EventLoop

GraphicsTexture Resource

packt

ActivityHandler

Background

GraphicsTileMap

GraphicsSprite Location

dbsdbs

RapidXml

SoundService

InputService

*Sound

InputHandler

Sensor

Handling Input Devices and Sensors

[ 300 ]

Project DroidBlaster_Part8-2 can be used as a

starng point for this part. The resulng project is provided

with this book under the name DroidBlaster_Part8-3.

Time for action – turning your device into a joypad

First, we need to handle sensor events in the event loop.

1. Open InputHandler.hpp and add a new method onAccelerometerEvent().

Include android/sensor.h ocial header for sensors.

#ifndef _PACKT_INPUTHANDLER_HPP_

#define _PACKT_INPUTHANDLER_HPP_

#include <android/input.h>

#include <android/sensor.h>

namespace packt {

class InputHandler {

public:

virtual ~InputHandler() {};

virtual bool onTouchEvent(AInputEvent* pEvent) = 0;

virtual bool onKeyboardEvent(AInputEvent* pEvent) = 0;

virtual bool onTrackballEvent(AInputEvent* pEvent) = 0;

virtual bool onAccelerometerEvent(ASensorEvent* pEvent) = 0;

};

}

#endif

2. Update jni/EventLoop.hpp class by adding a stac callback dedicated to

sensors named callback_sensor(). This method delegates processing to

member method processSensorEvent(), which redistributes events to

InputHandler instance.

A sensor event queue is represented by an ASensorManager opaque structure.

On the opposite of the acvity and input event queues, the sensor queue is not

managed by the native_app_glue module (as seen in Chapter 5, Wring a Fully

Nave Applicaon). We need to set it up ourselves with an ASensorEventQueue

and an android_poll_source:

#ifndef _PACKT_EVENTLOOP_HPP_

#define _PACKT_EVENTLOOP_HPP_

Chapter 8

[ 301 ]

...

namespace packt {

class EventLoop {

...

protected:

...

void processAppEvent(int32_t pCommand);

int32_t processInputEvent(AInputEvent* pEvent);

void processSensorEvent();

private:

friend class Sensor;

static void callback_event(android_app* pApplication,

int32_t pCommand);

static int32_t callback_input(android_app* pApplication,

AInputEvent* pEvent);

static void callback_sensor(android_app* pApplication,

android_poll_source* pSource);

private:

...

ActivityHandler* mActivityHandler;

InputHandler* mInputHandler;

ASensorManager* mSensorManager;

ASensorEventQueue* mSensorEventQueue;

android_poll_source mSensorPollSource;

};

}

#endif

3. Modify le jni/EventLoop.cpp, starng with its constructor:

#include "EventLoop.hpp"

#include "Log.hpp"

namespace packt {

EventLoop::EventLoop(android_app* pApplication) :

mEnabled(false), mQuit(false),

mApplication(pApplication),

mActivityHandler(NULL), mInputHandler(NULL),

Handling Input Devices and Sensors

[ 302 ]

mSensorPollSource(), mSensorManager(NULL),

mSensorEventQueue(NULL) {

mApplication->userData = this;

mApplication->onAppCmd = callback_event;

mApplication->onInputEvent = callback_input;

}

...

4. When starng an EventLoop in activate(), create a new sensor queue and

aach it with ASensorManager_createEventQueue() so that it gets polled

with the acvity and input event queues. LOOPER_ID_USER is a slot dened

inside native_app_glue to aach a custom queue to the internal glue Looper

(see Chapter 5, Wring a Fully Nave Applicaon. The glue Looper already has

two internal slots (LOOPER_ID_MAIN and LOOPER_ID_INPUT handled

transparently). Sensors are managed through a central manager ASensorManager

which can be retrieved using ASensorManager_getInstance().

In the deactivate() method, destroy the sensor event queue without mercy

with method ASensorManager_destroyEventQueue():

...

void EventLoop::activate() {

if ((!mEnabled) && (mApplication->window != NULL)) {

mSensorPollSource.id = LOOPER_ID_USER;

mSensorPollSource.app = mApplication;

mSensorPollSource.process = callback_sensor;

mSensorManager = ASensorManager_getInstance();

if (mSensorManager != NULL) {

mSensorEventQueue = ASensorManager_createEventQueue(

mSensorManager, mApplication->looper,

LOOPER_ID_USER, NULL, &mSensorPollSource);

if (mSensorEventQueue == NULL) goto ERROR;

}

mQuit = false; mEnabled = true;

if (mActivityHandler->onActivate() != STATUS_OK) {

goto ERROR;

}

return;

ERROR:

mQuit = true;

Chapter 8

[ 303 ]

deactivate();

ANativeActivity_finish(mApplication->activity);

}

void EventLoop::deactivate() {

if (mEnabled) {

mActivityHandler->onDeactivate();

mEnabled = false;

if (mSensorEventQueue != NULL) {

ASensorManager_destroyEventQueue(mSensorManager,

mSensorEventQueue);

mSensorEventQueue = NULL;

}

mSensorManager = NULL;

}

...

5. Finally, redirect sensor events to the handler in processSensorEvent().

Sensor events are wrapped in an ASensorEvent structure. This structure

contains a type eld to idenfy the sensor the event originates from

(here, to keep accelerometer events):

...

void EventLoop::processSensorEvent() {

ASensorEvent lEvent;

while (ASensorEventQueue_getEvents(mSensorEventQueue,

&lEvent, 1) > 0) {

switch (lEvent.type) {

case ASENSOR_TYPE_ACCELEROMETER:

mInputHandler->onAccelerometerEvent(&lEvent);

break;

}

void EventLoop::callback_sensor(android_app* pApplication,

android_poll_source* pSource) {

EventLoop& lEventLoop = *(EventLoop*) pApplication->userData;

lEventLoop.processSensorEvent();

}

Handling Input Devices and Sensors

[ 304 ]

6. Create a new le jni/Sensor.hpp as follows. The Sensor class is responsible for

the acvaon (with enable()) and deacvaon (with disable()) of the sensor.

Method toggle() is a wrapper to switch the sensor state.

This class works closely with EventLoop to process sensor messages (actually,

this code could have been integrated in EventLoop itself). Sensors themselves

are wrapped in an ASensor opaque structure and have a type (a constant dened

in android/sensor.h idencal to the ones in android.hardware.Sensor):

#ifndef _PACKT_SENSOR_HPP_

#define _PACKT_SENSOR_HPP_

#include "Types.hpp"

#include <android/sensor.h>

namespace packt {

class EventLoop;

class Sensor {

public:

Sensor(EventLoop& pEventLoop, int32_t pSensorType);

status toggle();

status enable();

status disable();

private:

EventLoop& mEventLoop;

const ASensor* mSensor;

int32_t mSensorType;

};

}

#endif

7. Implement Sensor in jni/Sensor.cpp le and write enable() in three steps:

Get a sensor of a specic type with ASensorManager_

getDefaultSensor().

Then, enable it with ASensorEventQueue_enableSensor() so that the

event queue receives related events.

Chapter 8

[ 305 ]

Set the desired event rate with ASensorEventQueue_setEventRate().

For a game, we typically want measures close to real me. The minimum

delay is queried with ASensor_getMinDelay() and seng it to a lower

value results in failure.

Obviously, we should perform this setup only when the sensor event queue

is ready. Sensor is deacvated in disable() with ASensorEventQueue_

disableSensor() thanks to the sensor instance retrieved previously.

#include "Sensor.hpp"

#include "EventLoop.hpp"

#include "Log.hpp"

namespace packt {

Sensor::Sensor(EventLoop& pEventLoop, int32_t pSensorType):

mEventLoop(pEventLoop),

mSensor(NULL),

mSensorType(pSensorType)

{}

status Sensor::toggle() {

return (mSensor != NULL) ? disable() : enable();

}

status Sensor::enable() {

if (mEventLoop.mEnabled) {

mSensor = ASensorManager_getDefaultSensor(

mEventLoop.mSensorManager, mSensorType);

if (mSensor != NULL) {

if (ASensorEventQueue_enableSensor(

mEventLoop.mSensorEventQueue, mSensor) < 0) {

goto ERROR;

}

int32_t lMinDelay = ASensor_getMinDelay(mSensor);

if (ASensorEventQueue_setEventRate(mEventLoop

.mSensorEventQueue, mSensor, lMinDelay) < 0) {

goto ERROR;

}

} else {

packt::Log::error("No sensor type %d", mSensorType);

}

Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >

Handling Input Devices and Sensors

[ 306 ]

return STATUS_OK;

ERROR:

Log::error("Error while activating sensor.");

disable();

return STATUS_KO;

}

status Sensor::disable() {

if ((mEventLoop.mEnabled) && (mSensor != NULL)) {

if (ASensorEventQueue_disableSensor(

mEventLoop.mSensorEventQueue, mSensor) < 0) {

goto ERROR;

}

mSensor = NULL;

}

return STATUS_OK;

ERROR:

Log::error("Error while deactivating sensor.");

return STATUS_KO;

}

Sensors are connected to our event loop. Let's handle sensor events in our

input service.

8. Manage the accelerometer sensor in jni/InputService.hpp. Add a method

stop() to disable sensors when service stops:

#ifndef _PACKT_INPUTSERVICE_HPP_

#define _PACKT_INPUTSERVICE_HPP_

#include "Context.hpp"

#include "InputHandler.hpp"

#include "Sensor.hpp"

#include "Types.hpp"

#include <android_native_app_glue.h>

namespace packt {

class InputService : public InputHandler {

public:

InputService(android_app* pApplication,

Chapter 8

[ 307 ]

Sensor* pAccelerometer,

const int32_t& pWidth, const int32_t& pHeight);

status start();

status update();

void stop();

...

public:

bool onTouchEvent(AInputEvent* pEvent);

bool onKeyboardEvent(AInputEvent* pEvent);

bool onTrackballEvent(AInputEvent* pEvent);

bool onAccelerometerEvent(ASensorEvent* pEvent);

private:

...

bool mMenuKey;

Sensor* mAccelerometer;

};

}

#endif

9. Rewrite update() to toggle the accelerometer when the menu buon is pressed

(instead of leaving the applicaon). Implement stop() to disable sensors when

applicaon is stopped (and save baery):

...

namespace packt {

InputService::InputService(android_app* pApplication,

Sensor* pAccelerometer,

const int32_t& pWidth, const int32_t& pHeight) :

mApplication(pApplication),

mHorizontal(0.0f), mVertical(0.0f),

mRefPoint(NULL), mWidth(pWidth), mHeight(pHeight),

mMenuKey(false),

mAccelerometer(pAccelerometer)

{}

...

status InputService::update() {

if (mMenuKey) {

if (mAccelerometer->toggle() != STATUS_OK) {

Handling Input Devices and Sensors

[ 308 ]

return STATUS_KO;

}

mMenuKey = false;

return STATUS_OK;

}

void InputService::stop() {

mAccelerometer->disable();

}

...

10. Here is the core code which computes direcon from the accelerometer captured

values. In the following code, X and Z axis express the roll and the pitch respecvely.

We check for both, the roll and the pitch, whether the device is in a neutral

orientaon (that is, CENTER_*) or sloping to the extreme (MIN_* and (MAX_*). Z

values need to be inverted:

Android devices can be naturally portrait-oriented (most smart-phones

if not all) or landscape-oriented (mostly tablets). This has an impact on

applicaons which require portrait or landscape mode: axes are not

aligned the same way. Use y-axis (that is, vector.y) instead of x axis in

the following piece for landscape oriented devices.

...

bool InputService::onAccelerometerEvent(ASensorEvent* pEvent) {

const float GRAVITY = ASENSOR_STANDARD_GRAVITY / 2.0f;

const float MIN_X = -1.0f; const float MAX_X = 1.0f;

const float MIN_Y = 0.0f; const float MAX_Y = 2.0f;

const float CENTER_X = (MAX_X + MIN_X) / 2.0f;

const float CENTER_Y = (MAX_Y + MIN_Y) / 2.0f;

float lRawHorizontal = pEvent->vector.x / GRAVITY;

if (lRawHorizontal > MAX_X) {

lRawHorizontal = MAX_X;

} else if (lRawHorizontal < MIN_X) {

lRawHorizontal = MIN_X;

}

mHorizontal = CENTER_X - lRawHorizontal;

float lRawVertical = pEvent->vector.z / GRAVITY;

Chapter 8

[ 309 ]

if (lRawVertical > MAX_Y) {

lRawVertical = MAX_Y;

} else if (lRawVertical < MIN_Y) {

lRawVertical = MIN_Y;

}

mVertical = lRawVertical - CENTER_Y;

return true;

}

11. In jni/DroidBlaster.cpp, call stop() to ensure sensors get disabled:

#include "DroidBlaster.hpp"

#include "Log.hpp"

namespace dbs {

...

void DroidBlaster::onDeactivate() {

packt::Log::info("Deactivating DroidBlaster");

mGraphicsService->stop();

mInputService->stop();

mSoundService->stop();

}

...

}

Let's terminate by inializing the input service properly aer all the

modicaons are done.

12. Finally, inialize the accelerometer in jni/Main.hpp. Because they are closely

related, move the EventLoop inializaon line on top:

...

#include "GraphicsService.hpp"

#include "InputService.hpp"

#include "Sensor.hpp"

#include "SoundService.hpp"

#include "TimeService.hpp"

#include "Log.hpp"

void android_main(android_app* pApplication) {

packt::EventLoop lEventLoop(pApplication);

packt::Sensor lAccelerometer(lEventLoop,

ASENSOR_TYPE_ACCELEROMETER);

Handling Input Devices and Sensors

[ 310 ]

packt::TimeService lTimeService;

packt::GraphicsService lGraphicsService(pApplication,

&lTimeService);

packt::InputService lInputService(pApplication,

&lAccelerometer,

lGraphicsService.getWidth(),lGraphicsService.getHeight());

packt::SoundService lSoundService(pApplication);

packt::Context lContext = { &lGraphicsService, &lInputService,

&lSoundService, &lTimeService };

dbs::DroidBlaster lDroidBlaster(&lContext);

lEventLoop.run(&lDroidBlaster, &lInputService);

}

What just happened?

We have created an event queue to listen to sensor events. Events are wrapped in an

ASensorEvent structure, dened in android/sensor.h. This structure provides the:

Sensor event origin, that is, which sensor produced this event.

Sensor event occurrence me.

Sensor output value. This value is stored in a union structure, that is, you

can use either one of the inside structures (here, we are interested in the

acceleration vector).

The same ASensorEvent structure is used for any Android sensor:

typedef struct ASensorEvent {

int32_t version;

int32_t sensor;

int32_t type;

int32_t reserved0;

int64_t timestamp;

union {

float data[16];

ASensorVector vector;

ASensorVector acceleration;

ASensorVector magnetic;

float temperature;

float distance;

float light;

float pressure;

};

Chapter 8

[ 311 ]

int32_t reserved1[4];

} ASensorEvent;

typedef struct ASensorVector {

union {

float v[3];

struct {

float x;

float y;

float z;

};

struct {

float azimuth;

float pitch;

float roll;

};

int8_t status;

uint8_t reserved[3];

} ASensorVector;

In our example, the accelerometer is set up with the lowest event rate possible, which may

vary between devices. It is important to note that sensor event rate has a direct impact on

baery saving! So use a rate that is sucient for your applicaon. ASensor_ API oers

some method to query available sensors and their capabilies: ASensor_getName(),

ASensor_getVendor(), ASensor_getMinDelay(), and so on.

Sensors have a unique idener, dened in android/sensor.h, which is the same on all

Android devices: ASENSOR_TYPE_ACCELEROMETER, ASENSOR_TYPE_MAGNETIC_FIELD,

ASENSOR_TYPE_GYRISCOPE ASENSOR_TYPE_LIGHT, ASENSOR_TYPE_PROXIMITY.

Addional sensors may exist and be available even if they are not named in android/

sensor.h header. On Gingerbread, this is the case of the gravity sensor (idener 9),

the linear acceleraon sensor (idener 10) and the rotaon vector (idener 11).

The sense of orientaon

The rotaon vector sensor, successor of the now deprecated orientaon

vector, is essenal in Augmented Reality applicaon. It gives you device

orientaon in 3D space. Combined with the GPS, it allows locang any object

through the eye of your device. The rotaon sensor provides a data vector,

which can be translated to an OpenGL view matrix thanks to the android.

hardware.SensorManager class (see its source code). An example is

provided with this book in DroidBlaster_Part8-3-Orientation.

Handling Input Devices and Sensors

[ 312 ]

Have a go hero – Handling screen rotation

There is sadly no way to get device rotaon relave to screen natural orientaon with nave

APIs. Thus, we need to rely on JNI to get current rotaon properly. The piece of Java code to

detect screen rotaon is the following:

WindowManager mgr = (InputMethodManager)

myActivity.getSystemService(Context.WINDOW_SERVICE);

int rotation = mgr.getDefaultDisplay().getRotation();

Rotaon values are can be ROTATION_0, ROTATION_90, ROTATION_180, or ROTATION_270

(provided in the Java class Surface). Write the equivalent JNI code in four steps:

1. Create a Configuration class which takes an android_app as constructor

parameter and whose only purpose is to provide the rotaon value.

2. In Configuration constructor, aach the JavaVM, retrieve the rotaon,

and nally detach the VM.

3. Instanate both the Configuration class in your android_main() method

and pass it to your InputService to get rotaon value.

4. Write a ulity method toScreenCoord() to convert canonical sensor coordinates

(that is, in the natural orientaon referenal) to screen coordinates:

void InputService::toScreenCoord(screen_rot pRotation,

ASensorVector* pCanonical, ASensorVector* pScreen) {

struct AxisSwap {

int8_t mNegX; int8_t mNegY;

int8_t mXSrc; int8_t mYSrc;

};

static const AxisSwap lAxisSwaps[] = {

{ 1, -1, 0, 1}, // ROTATION_0

{ -1, -1, 1, 0}, // ROTATION_90

{ -1, 1, 0, 1}, // ROTATION_180

{ 1, 1, 1, 0}}; // ROTATION_270

const AxisSwap& lSwap = lAxisSwaps[pRotation];

pScreen->v[0] = lSwap.mNegX * pCanonical->v[lSwap.mXSrc];

pScreen->v[1] = lSwap.mNegY * pCanonical->v[lSwap.mYSrc];

pScreen->v[2] = pCanonical->v[2];

}

This piece of code comes from an interesng document about sensors on the NVidia

developer site at http://developer.download.nvidia.com/tegra/docs/

tegra_android_accelerometer_v5f.pdf.

Chapter 8

[ 313 ]

5. Finally, x onAccelerometerEvent() to reverse accelerometer axis according

to the current screen rotaon. Just call the ulity method and use resulng X

and Z axes.

The nal project is provided with this book

in DroidBlaster_Part8-3-Keyboard.

Summary

In this chapter, we learnt dierent ways to interact with Android navely using input

and sensors. We discovered how to handle touch events. We also read key events from

keyboard and D-Pad and processed trackballs moon events. Finally, we have turned the

accelerometer into a Joypad. Because of Android fragmentaon, expect specicies in

input device's behavior and be prepared to adapt your code.

We have already been far in the capabilies of Android NDK in terms of applicaon structure,

graphics, sound, input, and sensors. But reinvenng the wheel is not a soluon! In the next

chapter, we are going to unleash the real power of Android by porng exisng libraries.

Porting Existing Libraries to Android

There are two main reasons why one would be interested in the Android NDK:

rst, for performance, and second, for portability. In the previous chapters,

we have seen how to access main nave Android APIs from nave code for

eciency purposes. In this chapter, we are going to bring the whole C/C++

ecosystem to Android. Well, at least discovering the path, as decades of C/

C++ development would be dicult to t the limited memory of mobile devices

anyway! Indeed, C and C++ are sll some of the most widely used programming

languages nowadays.

In previous NDK releases, portability was limited due to the paral support of

C++, especially Excepons and Run-Time Type informaon (or RTTI, a basic C++

reecon mechanism to get data types at runme such as instanceof in Java).

Any library requiring them could not be ported without modifying their code or

installing a custom NDK (the Crystax NDK, rebuilt by the community from ocial

sources and available at http://www.crystax.net/). Hopefully, many of

these restricons have been lied in NDK R5 (except wide character support).

In this chapter, in order to port exisng code to Android, we are going to learn how to:

Acvate the Standard Template Library and Boost framework

Enable excepons and Run Time Type Informaon (or RTTI)

Compile two open source libraries: Box2D and Irrlicht

Write Makeles to compile modules

By the end of this chapter, you should understand the nave building process and know

how to use Makeles appropriately.

Porng exisng libraries to Android

[ 316 ]

Developing with the Standard Template Library

The Standard Template Library (or STL) is a normalized library of containers, iterators,

algorithms, and helper classes, to ease most common programming operaons: dynamic

arrays, associave arrays, strings, sorng, and so on. This library gained reconnaissance

among developers over years and is widely spread. Developing in C++ without the STL

is like coding with one hand behind to the back!

Unl NDK R5, no STL was included. The whole C++ ecosystem was only one step ahead,

but not yet reachable. With some eorts, compiling an STL implementaon (for example,

STLport), for which excepons and RTTI were oponal, was possible, but only if the code

built upon did not require these features (unless building with the Crystax NDK). Anyway,

this nightmare is over, as STL and excepons are now ocially included. Two

implementaons can be chosen:

STLport, a mulplaorm STL, which is probably one of the most portable

implementaons, well accepted among open source projects

GNU STL (more commonly libstdc++), the ocial GCC STL

The STLport version included in the NDK R5 does not support excepons (RTTI being

supported from NDK R7) but can be used either as a shared or a stac library. On the

other hand, GNU STL supports excepons but is currently available as a stac library only.

In this rst part, let's embed STLport in DroidBlaster to ease collecon management.

Project DroidBlaster_Part8-3 can be used as a starng point

for this part. The resulng project is provided with this book under the

name DroidBlaster_Part9-1.

Time for action – embedding GNU STL in DroidBlaster

1. Create a jni/Application.mk le beside jni/Android.mk and write the

following content. That's it! Your applicaon is now STL-enabled, thanks to this

single line:

APP_STL = stlport_static

Of course, enabling the STL is useless, if we do not acvely use it in our code.

Let's take advantage of this opportunity to switch from asset les to external

les (on a sdcard or internal memory).

Chapter 9

[ 317 ]

2. Open the exisng le, jni/Resource.hpp, and:

Include the fstream stl header to read les.

Replace the Asset management members with an ifstream object

(that is, an input le stream). We are also going to need a buer for the

bufferize() method.

Remove the descript() method and the ResourceDescriptor class.

Descriptors work with the Asset API only.

#ifndef _PACKT_RESOURCE_HPP_

#define _PACKT_RESOURCE_HPP_

#include "Types.hpp"

#include <fstream>

namespace packt {

...

class Resource {

...

private:

const char* mPath;

std::ifstream mInputStream;

char* mBuffer;

};

}

#endif

3. Open the corresponding implementaon le jni/Resource.cpp. Replace the

previous implementaon, based on the asset management API with STL streams.

Files will be opened in binary mode (even the le map XML le that is going to be

directly buered in memory). To read the le length, we can use the stat() POSIX

primive. Method bufferize() is emulated with a temporary buer:

#include "Resource.hpp"

#include "Log.hpp"

#include <sys/stat.h>

namespace packt {

Resource::Resource(android_app* pApplication, const char*

pPath):

Porng exisng libraries to Android

[ 318 ]

mPath(pPath), mInputStream(), mBuffer(NULL)

{}

status Resource::open() {

mInputStream.open(mPath, std::ios::in | std::ios::binary);

return mInputStream ? STATUS_OK : STATUS_KO;

}

void Resource::close() {

mInputStream.close();

delete[] mBuffer; mBuffer = NULL;

}

status Resource::read(void* pBuffer, size_t pCount) {

mInputStream.read((char*)pBuffer, pCount);

return (!mInputStream.fail()) ? STATUS_OK : STATUS_KO;

}

const char* Resource::getPath() {

return mPath;

}

off_t Resource::getLength() {

struct stat filestatus;

if (stat(mPath, &filestatus) >= 0) {

return filestatus.st_size;

} else {

return -1;

}

const void* Resource::bufferize() {

off_t lSize = getLength();

if (lSize <= 0) return NULL;

mBuffer = new char[lSize];

mInputStream.read(mBuffer, lSize);

if (!mInputStream.fail()) {

return mBuffer;

} else {

return NULL;

}

These changes to the reading system should all be transparent. Except one.

Chapter 9

[ 319 ]

4. Background music was previously played through an asset descriptor. Now, we

provide a real le. So, in jni/SoundService.cpp, change the data source by

replacing the SLDataLocator_AndroidFD structure with SLDataLocation_URI.

The le locaon has to be prexed with file://, when it comes from the sdcard

(it could also be, for example, http://, if the le was coming from a server). To

help building the nal URI, concatenate the prex and the path using STL strings.

The le is sll an MP3, so the data format does not change:

#include "SoundService.hpp"

#include "Resource.hpp"

#include "Log.hpp"

#include <string>

namespace packt {

...

status SoundService::playBGM(const char* pPath) {

SLresult lRes;

Log::info("Opening BGM %s", pPath);

SLDataLocator_URI lDataLocatorIn;

std::string lPath = std::string("file://") + pPath;

lDataLocatorIn.locatorType = SL_DATALOCATOR_URI;

lDataLocatorIn.URI = (SLchar*) lPath.c_str();

SLDataFormat_MIME lDataFormat;

lDataFormat.formatType = SL_DATAFORMAT_MIME;

...

return STATUS_OK;

ERROR:

return STATUS_KO;

}

...

}

Porng exisng libraries to Android

[ 320 ]

5. Copy resources in your asset directory to your sdcard (or internal memory,

depending on your device) in the directory droidblaster (for example,

/sdcard/droidblaster).

Almost all Android devices can store les in an addional storage locaon

mounted in directory /sdcard. "Almost" is the important word here… Since

the rst Android G1, the meaning of "sdcard" has changed. Some recent

devices have an external storage that is in fact internal (e.g. ash memory

on some tablets), and some others have a second storage locaon at their

disposal (although in most cases, the second storage is mounted inside /

sdcard). Moreover, path /sdcard is not engraved into the marble…

To detect safely the addional storage locaon, the only soluon

is to rely on JNI, by calling android.os.Environment.

getExternalStorageDirectory(). You can also check that storage

is available with getExternalStorageState(). Note that the word

"External" in API method names is here for historical reasons only.

Replace paths to resources in each le that needs one (change the path

if necessary):

/sdcard/droidblaster/tilemap.png in jni/Background.cpp.

/sdcard/droidblaster/tilemap.tmx in jni/Background.cpp.

/sdcard/droidblaster/start.pcm in jni/DroidBlaster.cpp.

/sdcard/droidblaster/bgm.mp3 in jni/DroidBlaster.cpp.

/sdcard/droidblaster/ship.png in jni/Ship.cpp.

6. Run the applicaon. Noced it? Everything runs like before!

Now, let's take advantage of the STL to give some company to our lonely ship.

7. First, let's create a lile randomizaon helper macro in exisng le jni/Type.hpp:

#ifndef _PACKT_TYPES_HPP_

#define _PACKT_TYPES_HPP_

#include <stdint.h>

#include <cstdlib>

namespace packt {

...

}

#define RAND(pMax) (float(pMax) * float(rand()) / float(RAND_MAX))

#endif

Chapter 9

[ 321 ]

8. The random value generator has to be inialized rst, with a seed. A possible

soluon is to set the seed value to the current me in jni/TimeService.cpp:

#include "TimeService.hpp"

#include "Log.hpp"

#include <cstdlib>

namespace packt {

TimeService::TimeService() :

mElapsed(0.0f),

mLastTime(0.0f) {

srand(time(NULL));

}

...

}

9. Create a new header le jni/Asteroid.hpp, similar to the one used for the

Ship game object, to represent a dangerous and frightening asteroid:

#ifndef _DBS_ASTEROID_HPP_

#define _DBS_ASTEROID_HPP_

#include "Context.hpp"

#include "GraphicsService.hpp"

#include "GraphicsSprite.hpp"

#include "Types.hpp"

namespace dbs {

class Asteroid {

public:

Asteroid(packt::Context* pContext);

void spawn();

void update();

private:

packt::GraphicsService* mGraphicsService;

packt::TimeService* mTimeService;

packt::GraphicsSprite* mSprite;

packt::Location mLocation;

float mSpeed;

};

}

#endif

Porng exisng libraries to Android

[ 322 ]

10. Implement the Asteroid class in jni/Asteroid.cpp. An asteroid is represented

with a sprite loaded at construcon me.

The Asteroid game object itself is inialized in spawn(), above the top of the

screen (that is, they are inially hidden). Asteroids are distributed randomly over

screen width and have a random animaon and movement speed.

During frame processing in update(), asteroids fall from top to boom, according

to their speed. When they reach the boom, they are recreated.

#include "Asteroid.hpp"

#include "Log.hpp"

namespace dbs {

Asteroid::Asteroid(packt::Context* pContext) :

mTimeService(pContext->mTimeService),

mGraphicsService(pContext->mGraphicsService),

mLocation(), mSpeed(0.0f) {

mSprite = pContext->mGraphicsService->registerSprite(

mGraphicsService->registerTexture(

"/sdcard/droidblaster/asteroid.png"),

64, 64, &mLocation);

}

void Asteroid::spawn() {

const float MIN_SPEED = 4.0f;

const float MIN_ANIM_SPEED = 8.0f, ANIM_SPEED_RANGE = 16.0f;

mSpeed = -RAND(mGraphicsService->getHeight()) - MIN_SPEED;

float lPosX = RAND(mGraphicsService->getWidth());

float lPosY = RAND(mGraphicsService->getHeight())

+ mGraphicsService->getHeight();

mLocation.setPosition(lPosX, lPosY);

float lAnimSpeed = MIN_ANIM_SPEED + RAND(ANIM_SPEED_RANGE);

mSprite->setAnimation(8, -1, lAnimSpeed, true);

}

void Asteroid::update() {

mLocation.translate(0.0f, mTimeService->elapsed() * mSpeed);

if (mLocation.mPosY <= 0) {

spawn();

}

Chapter 9

[ 323 ]

11. Open the jni/DroidBlaster.hpp header and include the vector header, the

most common STL container that encapsulates C arrays. Then, declare a vector of

asteroid pointers (prexed with the std namespace):

#ifndef _PACKT_DROIDBLASTER_HPP_

#define _PACKT_DROIDBLASTER_HPP_

#include "ActivityHandler.hpp"

#include "Asteroid.hpp"

#include "Background.hpp"

#include "Context.hpp"

...

#include "Types.hpp"

#include <vector>

namespace dbs {

class DroidBlaster : public packt::ActivityHandler

{

...

private:

...

Background mBackground;

Ship mShip;

std::vector<Asteroid*> mAsteroids;

packt::Sound* mStartSound;

};

}

#endif

12. Finally, open jni/DroidBlaster.cpp. Include this new container in the

constructor inializaon list and insert Asteroid instances with method

push_back().

Then, in the destructor, we can iterate through the vector using an iterator to

release every vector entry. Syntax is a bit more tedious, but gives more exibility:

#include "DroidBlaster.hpp"

#include "Log.hpp"

namespace dbs {

DroidBlaster::DroidBlaster(packt::Context* pContext) :

Porng exisng libraries to Android

[ 324 ]

mGraphicsService(pContext->mGraphicsService),

mInputService(pContext->mInputService),

mSoundService(pContext->mSoundService),

mTimeService(pContext->mTimeService),

mBackground(pContext), mShip(pContext), mAsteroids(),

mStartSound(mSoundService->registerSound(

"/sdcard/droidblaster/start.pcm")) {

for (int i = 0; i < 16; ++i) {

mAsteroids.push_back(new Asteroid(pContext));

}

DroidBlaster::~DroidBlaster() {

std::vector<Asteroid*>::iterator iAsteroid =

mAsteroids.begin();

for (; iAsteroid < mAsteroids.end() ; ++iAsteroid) {

delete *iAsteroid;

}

mAsteroids.clear();

}

...

13. Sll in jni/DroidBlaster.cpp, apply the same iteraon technique to inialize

asteroid game objects (in onActivate()) and iterate each frame (in onStep()):

...

packt::status DroidBlaster::onActivate() {

...

mBackground.spawn();

mShip.spawn();

std::vector<Asteroid*>::iterator iAsteroid =

mAsteroids.begin();

for (; iAsteroid < mAsteroids.end() ; ++iAsteroid) {

(*iAsteroid)->spawn();

}

mTimeService->reset();

return packt::STATUS_OK;

}

...

Chapter 9

[ 325 ]

packt::status DroidBlaster::onStep() {

mTimeService->update();

mBackground.update();

mShip.update();

std::vector<Asteroid*>::iterator iAsteroid =

mAsteroids.begin();

for (; iAsteroid < mAsteroids.end(); ++iAsteroid) {

(*iAsteroid)->update();

}

// Updates services.

...

return packt::STATUS_OK;

}

...

}

14. Copy the asteroid.png sprite sheet to your droidblaster storage directory.

File asteroid.png is provided with this book in Chapter9/Resource.

What just happened?

We have seen how to access a binary le located on the SD-Card through STL streams. All

asset les became simple les on the addional storage. This change can be made almost

transparent at the excepon of OpenSL ES MIME player, which needs a dierent locator.

We have also seen how to manipulate STL strings and avoid using the complex C string

manipulaon primives.

Finally, we have implemented a set of Asteroid game objects managed inside an STL

container vector, instead of a raw C array. STL containers automacally handle memory

management (array resizing operaons and so on). File access happens like on any Unix

le systems, SD-Card being available from a mount point (located generally, but not always,

in /sdcard).

SD-card storage should always be considered for applicaons with heavy resource

les. Indeed, installing heavy APK causes trouble on memory-limited devices.

Porng exisng libraries to Android

[ 326 ]

Android and endianness

Beware of plaorm and le endianness with external les. Although all

ocial Android devices are lile-endian, there is no guarantee this will

remain true (for example, there exist some unocial ports for Android on

other CPU architectures). ARM supports both lile-and big-endian encoding,

whereas x86 (available since NDK R6) are lile-endian only. Endian encoding

is converble, thanks to POSIX primives declared in endian.h.

We have linked STLport as a stac library. But, we could have linked it dynamically, or linked

to the GNU STL. Which choice to make depends on your needs:

No excepons or RTTI needed, but STL required by several libraries: In that case, if a

consequent subset of STL features is necessary, stlport_shared should be used.

No excepons or RTTI needed and STL used by a single library or only a small subset

required: Consider using stlport_static instead, as memory usage may be

lower.

Excepon handling or RTTI are needed: Link against gnustl_static.

Since NDK R7, RTTI are supported by STLport, but not excepons.

STL is denitely a huge improvement that avoids repeve and error-prone code. Many

open source libraries require it and can now be ported without much trouble. More

documentaon about it can be found at http://www.cplusplus.com/reference/stl

and on SGI's website (publisher of the rst STL), at http://www.sgi.com/tech/stl.

Static versus shared

Remember that shared libraries need to be loaded manually at runme. If you forget to

load one of them, an error is raised, as soon as dependent libraries (or the applicaon)

are loaded. As it is not possible to predict in advance which funcons are going to be

called, they are loaded enrely in memory, even if most of their contents remain unused.

On the other hand, stac libraries are de facto loaded with dependent libraries. Indeed, stac

libraries do not really exist as such. They are copied into dependent libraries during linking.

The drawback is that binary code may get duplicated in each library, and memory is thus

wasted. However, since the linker knows precisely which part of the library gets called from the

embedding code, it can copy only what is needed, resulng in a limited size aer compilaon.

Chapter 9

[ 327 ]

Also remember that a Java applicaon can load shared libraries only (which can be

themselves linked against either shared or stac libraries). With a nave acvity, the main

shared library is specied through the android.app.lib_name property, in the applicaon

manifest. Libraries referenced from another library must be loaded manually before. The

NDK does not do this itself.

Shared libraries can be loaded easily, using System.loadLibrary() in a JNI applicaon.

But, a NativeActivity is transparent. So, if you decide to use shared libraries, then

the only soluon is to write your own Java acvity, inhering from NativeActivity

and invoking the appropriate loadLibrary() direcves. For instance, below is what

DroidBlaster acvity would look like, if we were using stlport_shared instead:

package com.packtpub.droidblaster

import android.app.NativeActivity

public class MyNativeActivity extends NativeActivity {

static {

System.loadLibrary("stlport_shared");

System.loadLibrary("droidblaster");

}

STL performances

When developing for performance, a standard STL container is not always the best

choice, especially in terms of memory management and allocaon. Indeed, STL is an

all-purpose library, wrien for common cases. Alternave libraries should be considered

for performance-crical code. A few examples are:

EASTL: An STL replacement library, developed by Electronic Arts, and developed

with gaming in mind. Only 50 percent of the projects have been released (as part

of the EA open source program), which are nevertheless highly interesng. An

extract is available in the repository https://github.com/paulhodge/EASTL.

A must-read paper detailing EASTL technical details can be found on the Open

Standards website at http://www.open-std.org/jtc1/sc22/wg21/docs/

papers/2007/n2271.html.

RDESTL: It is an open source subset of the STL, based on the EASTL technical paper,

which was published several years before EASTL code release. The code repository

can be found at http://code.google.com/p/rdestl/.

Google SparseHash: For a high performance associave array library (note that

RDESTL is also quite good at that).

This is far from exhausve. Just dene your exact needs to make the most appropriate choice.

Porng exisng libraries to Android

[ 328 ]

Compiling Boost on Android

If STL is the most common framework among C++ programs, Boost probably comes right

aer. A real Swiss army knife, this toolkit contains a profusion of ulies to handle most

common needs, and even more! The most popular features of Boost are smart pointers, an

encapsulaon of raw pointers in a reference-counng class to handle memory allocaon, and

deallocaon automacally. They avoid most memory leaks or pointer misuse for almost free.

Boost, like STL, is mainly a template library, which means that no compilaon is needed for

most of its modules. For instance, including the smart pointer header le is enough to use

them. However, a few of its modules need to be compiled as a library rst (for example, the

threading module).

We are now going to see how to build Boost on the Android NDK and replace raw,

unmanaged pointers with smarter ones.

Project DroidBlaster_Part9-1 can be used as a starng

point for this part. The resulng project is provided with this book,

under the name DroidBlaster_Part9-2.

Time for action – embedding Boost in DroidBlaster

1. Download Boost from http://www.boost.org/ (version 1.47.0, in this book).

The Boost 1.47.0 archive is provided with this book in

directory Chapter09/Library.

2. Uncompress the archive into ${ANDROID_NDK}/sources. Name the

directory boost.

3. Open a command line window and go to the boost directory. Launch bootstrap.

bat on Windows or the ./bootstrap.sh script on Linux and Mac OS X, to build

b2. This program, previously named BJam, is a custom building tool similar to Make.

4. Open the le boost/tools/build/v2/user-config.jam. This le is, like

its name suggests, a conguraon le that can be set up to customize Boost

compilaon.

Update user-config.jam. Initial content contains only comments

and can be erased:

import os ;

Chapter 9

[ 329 ]

if [ os.name ] = CYGWIN || [ os.name ] = NT {

androidPlatform = windows ;

}

else if [ os.name ] = LINUX {

androidPlatform = linux-x86 ;

}

else if [ os.name ] = MACOSX {

androidPlatform = darwin-x86 ;

}

...

5. Compilaon is performed stacally. BZip is deacvated, because it is unavailable,

by default, on Android (we could however compile it separately):

...

modules.poke : NO_BZIP2 : 1 ;

...

6. Compiler is recongured to use the NDK GCC toolchain (g++, ar, and ranlib) in

stac mode (the ar archiver being in charge of creang the stac library). Direcve

sysroot indicates which Android API release to compile and link against. The

specied directory is located in the NDK and contains include les and libraries

specic to this release:

...

ANDROID_NDK = ../.. ;

using gcc : android4.4.3 :

$(ANDROID_NDK)/toolchains/arm-linux-androideabi-4.4.3/

prebuilt/$(androidPlatform)/bin/arm-linux-androideabi-g++ :

<archiver>$(ANDROID_NDK)/toolchains/arm-linux-

androideabi-4.4.3/prebuilt/$(androidPlatform)/bin/arm-linux-

androideabi-ar

<ranlib>$(ANDROID_NDK)/toolchains/arm-linux-androideabi-4.4.3/

prebuilt/$(androidPlatform)/bin/arm-linux-androideabi-ranlib

<compileflags>--sysroot=$(ANDROID_NDK)/platforms/android-9/

arch-arm

<compileflags>-I$(ANDROID_NDK)/sources/cxx-stl/gnu-libstdc++/

include

<compileflags>-I$(ANDROID_NDK)/sources/cxx-stl/gnu-libstdc++/

libs/armeabi/include

...

Porng exisng libraries to Android

[ 330 ]

7. A few opons have to be dened to tweak Boost compilaon:

NDEBUG to deacvate debug mode

BOOST_NO_INTRINSIC_WCHAR_T to indicate the lack of support for wide

chars

BOOST_FILESYSTEM_VERSION is set to 2, because the latest version of

Boost FileSystem module (version 3) brings incompable changes related

to wide chars

no-strict-aliasing to disable opmizaons related to type aliasing

-02 to specify opmizaon level

...

<compileflags>-DNDEBUG

<compileflags>-D__GLIBC__

<compileflags>-DBOOST_NO_INTRINSIC_WCHAR_T

<compileflags>-DBOOST_FILESYSTEM_VERSION=2

<compileflags>-lstdc++

<compileflags>-mthumb

<compileflags>-fno-strict-aliasing

<compileflags>-O2

;

8. With the previously opened terminal, sll in the boost directory, launch

compilaon using the command line below. We need to exclude two modules

not working with the NDK:

The Serializaon module, which requires wide characters (not supported

by the ocial NDK yet)

Python, which requires addional libraries not available on the NDK

by default

b2 --without-python --without-serialization toolset=gcc-

android4.4.3 link=static runtime-link=static target-os=linux

--stagedir=android

9. Compilaon should take quite some me, but eventually it will fail! Launch

compilaon a second me to nd the error message hidden inside thousands of

lines the rst me. You should get a ::statvfs has not been declared... This problem

is related to boost/libs/filesystem/v2/src/v2_operations.cpp. This

le, normally at line 62, includes the sys/statvfs.h system header. However,

the Android NDK provides sys/vfs.h instead. We have to include it in v2_

operations.cpp:

Chapter 9

[ 331 ]

Android is (more or less) a Linux with its own specicies. If a library does

not take them into account (yet!), expect to encounter these kinds of

annoyances frequently.

...

# else // BOOST_POSIX_API

# include <sys/types.h>

# if !defined(__APPLE__) && !defined(__OpenBSD__) \

&& !defined(__ANDROID__)

# include <sys/statvfs.h>

# define BOOST_STATVFS statvfs

# define BOOST_STATVFS_F_FRSIZE vfs.f_frsize

# else

#ifdef __OpenBSD__

# include <sys/param.h>

#elif defined(__ANDROID__)

# include <sys/vfs.h>

#endif

# include <sys/mount.h>

# define BOOST_STATVFS statfs

...

10. Compile again. No message …failed updang X targets… should appear this me.

Libraries are compiled in ${ANDROID_NDK}/boost/android/lib/.

11. Several other incompabilies may appear when using the various modules of

Boost. For example, if you prefer to generate a random number with Boost and

decide to include boost/random.hpp, you will encounter a compilaon error

related to endianness. To x it, add a denion for Android in boost/boost/

detail/endian.hpp, at line 34:

...

#if defined (__GLIBC__) || defined(__ANDROID__)

# include <endian.h>

# if (__BYTE_ORDER == __LITTLE_ENDIAN)

# define BOOST_LITTLE_ENDIAN

...

The patches applied in previous steps are provided with this

book in directory Chapter09/Library/boost_1_47_0_

android, along with compiled binaries.

Porng exisng libraries to Android

[ 332 ]

12. Sll in the boost directory, create a new Android.mk le to declare the newly

compiled libraries as Android modules. It needs to contain one module declaraon

per module. For example, dene one library boost_thread, referencing the

stac library android/lib/libboost_thread.a. Variable LOCAL_EXPORT_C_

INCLUDES is important to automacally append boost includes when referenced

from a program:

LOCAL_PATH:= $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE:= boost_thread

LOCAL_SRC_FILES:= android/lib/libboost_thread.a

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)

include $(PREBUILT_STATIC_LIBRARY)

More modules can be declared in the same le with the same set of lines (for

example, boost_iostreams, etc.).

Android.mk is provided in Chapter09/Library/

boost_1_47_0_android.

Now, let's use Boost in our own project.

13. Go back to the DroidBlaster project. To include Boost in an applicaon, we need to

link with an STL implementaon supporng excepons. Thus, we need to replace

STLport with GNU STL (available as a stac library only) and acvate excepons:

APP_STL := gnustl_static

APP_CPPFLAGS := -fexceptions

14. Finally, open your Android.mk le and include a Boost module to check that

everything works. For example, try the Boost thread module:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LS_CPP=$(subst $(1)/,,$(wildcard $(1)/*.cpp))

LOCAL_MODULE := droidblaster

LOCAL_SRC_FILES := $(call LS_CPP,$(LOCAL_PATH))

LOCAL_LDLIBS := -landroid -llog -lEGL -lGLESv1_CM -lOpenSLES

Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >

Chapter 9

[ 333 ]

LOCAL_STATIC_LIBRARIES := android_native_app_glue png boost_thread

include $(BUILD_SHARED_LIBRARY)

$(call import-module,android/native_app_glue)

$(call import-module,libpng)

$(call import-module,boost)

DroidBlaster is now Boost-enabled! First, let's see if excepons work.

15. Edit jni/GraphicsTilemap.cpp. Remove the RapidXML error handling block

and replace the call to setjmp() with a C++ try/catch. Catch a parse_error

excepon:

...

namespace packt {

...

int32_t* GraphicsTileMap::loadFile() {

...

mResource.close();

}

try {

lXmlDocument.parse<parse_default>(lFileBuffer);

} catch (rapidxml::parse_error& parseException) {

packt::Log::error("Error while parsing TMX file.");

packt::Log::error(parseException.what());

goto ERROR;

}

...

}

Now, we could use smart pointers to manage memory allocaon and deallocaon

automacally.

16. Boost and STL tends to cause a proliferaon of unreadable denions. Let's simplify

their use by dening custom smart pointer and vector types with the typedef

keyword in jni/Asteroid.hpp. The vector type contains smart pointers instead

of raw pointers:

#ifndef _DBS_ASTEROID_HPP_

#define _DBS_ASTEROID_HPP_

#include "Context.hpp"

#include "GraphicsService.hpp"

Porng exisng libraries to Android

[ 334 ]

#include "GraphicsSprite.hpp"

#include "Types.hpp"

#include <boost/shared_ptr.hpp>

#include <vector>

namespace dbs {

class Asteroid {

...

public:

typedef boost::ptr <Asteroid> ptr;

typedef std::vector<shared> vec;

typedef vec::iterator vec_it;

}

#endif

17. Open jni/DroidBlaster.hpp and remove the vector header inclusion (now

included in jni/Asteroid.hpp). Use the newly dened type Android::vec:

...

namespace dbs {

class DroidBlaster : public packt::ActivityHandler {

...

private:

...

Background mBackground;

Ship mShip;

Asteroid::vec mAsteroids;

packt::Sound* mStartSound;

};

}

#endif

18. Every iterator declaraon involving asteroids now needs to be switched with the

new 'typedefed" types. Code is not much dierent except one thing… Look carefully:

the destructor is now empty! All pointers are deallocated automacally by Boost:

#include "DroidBlaster.hpp"

#include "Log.hpp"

namespace dbs {

DroidBlaster::DroidBlaster(packt::Context* pContext) :

Chapter 9

[ 335 ]

... {

for (int i = 0; i < 16; ++i) {

Asteroid::ptr lAsteroid(new Asteroid(pContext));

mAsteroids.push_back(lAsteroid);

}

DroidBlaster::~DroidBlaster()

{}

packt::status DroidBlaster::onActivate() {

...

mBackground.spawn();

mShip.spawn();

Asteroid::vec_it iAsteroid = mAsteroids.begin();

for (; iAsteroid < mAsteroids.end() ; ++iAsteroid) {

(*iAsteroid)->spawn();

}

mTimeService->reset();

return packt::STATUS_OK;

}

...

packt::status DroidBlaster::onStep() {

mTimeService->update();

mShip.update();

Asteroid::vec_it iAsteroid = mAsteroids.begin();

for (; iAsteroid < mAsteroids.end(); ++iAsteroid) {

(*iAsteroid)->update();

}

if (mGraphicsService->update() != packt::STATUS_OK) {

...

return packt::STATUS_OK;

}

Porng exisng libraries to Android

[ 336 ]

What just happened?

We have xed a minor issue with Boost code and wrien the proper conguraon to compile

it. Finally, we have discovered one of Boost's most famous (and helpful!) features: smart

pointers. But Boost provides much more. See its documentaon, located at http://www.

boost.org/doc/libs, to discover its full richness. You can nd informaon about Android

issues on the bug tracker.

We have compiled Boost manually, using its dedicated building tool b2, customized to use

the NDK tool chain. Then, prebuilt stac libraries have been published using an Android.

mk and imported into a nal applicaon with NDK import-module direcve. Every me

Boost is updated or a modicaon is made, code has to be manually compiled again with b2.

Only the nal prebuilt library is imported into client applicaon with PREBUILT_STATIC_

LIBRARY direcve (and the shared library equivalent PREBUILT_SHARED_LIBRARY). On the

other hand, BUILD_STATIC_LIBRARY and BUILD_SHARED_LIBRARY would recompile the

whole module each me a new client applicaon imports it or changes its own compilaon

sengs (for example, when switching APP_OPTIM from debug to release in Application.

mk).

To make Boost work, we have switched from STLport to GNU STL, which is currently the

only one to support excepons. This replacement occurs in the Application.mk le,

by replacing stlport_static with gnustl_static. Excepons and RTTI are acvated

very easily by appending -fexceptions and -frtti, respecvely, to the APP_CPPFLAGS

direcve in the same le, or the LOCAL_CPPFLAGS of the concerned library. By default,

Android compiles with -fno-exceptions and -fno-rtti ags.

A problem? Clean!

It happens oen, especially when switching from one STL to another, that

libraries do not get recompiled well. Sadly, this results in rather weird and

obscure undened link errors. If you have a doubt, just clean your project from

the Eclipse menu | Project/Clean... or the command ndk-build clean, in

your applicaon root directory.

Excepons have the reputaon of making the compiled code bigger and less ecient.

They prevent the compiler from performing some clever opmizaons. However, whether

excepons are worse than error checking or even no check at all is a highly debatable queson.

In fact, Google's engineers dropped them in rst releases because GCC 3.x generated poor

excepon handling code for ARM processors. However, the build chain now uses GCC 4.x,

which does not suer from this aw. Compared to manual error checking and handling of

exceponal cases, penalty should not be signicant most of the me, assuming excepons

are used for exceponal cases only. Thus, the choice of excepons or not is up to you

(and your embedded libraries)!

Chapter 9

[ 337 ]

Excepon handling in C++ is not easy and imposes a strict discipline!

They must be used strictly for exceponal cases and require carefully

designed code. Have a look at the Resource Acquision Is

Inializaon (abbreviated RAII) idiom to properly handle them.

Have a go hero – threading with Boost

DroidBlaster is now a bit safer, thanks to smart pointers. However, smart pointers are

based on template les. There is no need to link against Boost modules to use them. So,

to check if this works, modify the DroidBlaster class to launch a Boost thread updates

asteroids in the background. The thread must be run in a separate method (for example,

updateBackground()). You can launch the thread itself from onStep() and join it (that is,

wait for the thread to terminate its task) before the GraphicsService draws its content:

...

#include <boost/thread.hpp>

...

void DroidBlaster::updateThread() {

Asteroid::vec_it iAsteroid = mAsteroids.begin();

for (; iAsteroid < mAsteroids.end(); ++iAsteroid) {

(*iAsteroid)->update();

}

packt::status DroidBlaster::onStep() {

mTimeService->update();

boost::thread lThread(&DroidBlaster::updateThread, this);

mBackground.update();

mShip.update();

lThread.join();

if (mGraphicsService->update() != packt::STATUS_OK) {

...

}

...

The nal result is available in project DroidBlaster_Part9-2-Thread,

provided with this book.

Porng exisng libraries to Android

[ 338 ]

If you have experience with threads, this piece of code will probably make you jump out of

your chair. Indeed, this is the best example of what should not be done with threads because:

Funconal division (for example, one service in its own thread) is generally not the

best way to achieve threading eciently.

Only a few mobile processors are mul-cores (but this fact is changing really fast).

Thus, creang a thread on a single processor will not improve performance, except

for blocking operaons such as I/O.

Mul-cores can have more than just 2 cores! Depending on the problem to solve,

it can be a good idea to have as many threads as cores.

Creang threads on demand is not ecient. Thread pools are a beer approach.

Threading is a really complex maer and should be taken it into account

early in your design. The Intel developer website (http://software.

intel.com/) provides lots of interesng resources about threading and

a library named Threading Building Block, which is a good reference in

design terms (but not ported on Android, yet, despite some progress).

Porting third-party libraries to Android

With the Standard Template Library and Boost in our basket, we are ready to port almost any

library to Android. Actually, many third-party libraries have been already ported and many

more are coming. But when nothing is available, we have to rely on our own skills to port

them. In this nal part, we are going to compile two of them:

Box2D: It is a highly popular open source physics simulaon engine, embedded

in many 2D games such as Angry Birds (quite a good reference!). It is available in

several languages, Java included. But, its primary language is C++.

Irrlicht: It is a real-me open source 3D engine. It is cross-plaorm and oers

DirectX, OpenGL, and GLES bindings.

We are going to use them in the next chapter to implement the DroidBlaster physics layer

and brings graphics to the third dimension.

Project DroidBlaster_Part9-2 can be used as a starng point for

this part. The resulng project is provided with this book, under

the name DroidBlaster_Part9-3.

Chapter 9

[ 339 ]

Time for action – compiling Box2D and Irrlicht with the NDK

First, let's try to port Box2D on the Android NDK.

The Box2D 2.2.1 archive is provided with this book, in

directory Chapter09/Library.

1. Go to http://www.box2d.org/ and download the Box2D source archive (2.2.1

in this book). Uncompress it into ${ANDROID_NDK}/sources/ and name the

directory box2d.

2. Create and open an Android.mk le in the root of the box2d directory.

Save the current directory inside the LOCAL_PATH variable. This step is always

necessary, because an NDK build system may switch to another directory at

any me during compilaon.

LOCAL_PATH:= $(call my-dir)

...

3. Then, list all Box2D source les to compile. We are interested in source le name

only, which can be found in ${ANDROID_NDK}/sources/box2d/Box2D/Box2D.

Use the LS_CPP helper funcon to avoid copying each lename.

...

LS_CPP=$(subst $(1)/,,$(wildcard $(1)/$(2)/*.cpp))

BOX2D_CPP:= $(call LS_CPP,$(LOCAL_PATH),Box2D/Collision) \

$(call LS_CPP,$(LOCAL_PATH),Box2D/Collision/Shapes) \

$(call LS_CPP,$(LOCAL_PATH),Box2D/Common) \

$(call LS_CPP,$(LOCAL_PATH),Box2D/Dynamics) \

$(call LS_CPP,$(LOCAL_PATH),Box2D/Dynamics/Contacts) \

$(call LS_CPP,$(LOCAL_PATH),Box2D/Dynamics/Joints) \

$(call LS_CPP,$(LOCAL_PATH),Box2D/Rope)

...

4. Then, write the Box2D module denion for a stac library. First, call the $

(CLEAR_VARS) script. This script has to be included before any module denion,

to remove any potenal change made by other modules and avoid any unwanted

side eects. Then, dene the following sengs:

Module name in LOCAL_MODULE: Module name is suxed with

_static to avoid a name clash with the shared version we are going

to dene right aer.

Module source les in LOCAL_SRC_FILES (using BOX2D_CPP dened

previously).

Porng exisng libraries to Android

[ 340 ]

Include le directory provided to clients in LOCAL_EXPORT_C_INCLUDES.

Include le used internally for module compilaon in LOCAL_C_INCLUDES.

Here, client include les and compilaon include les are the same (and are

oen the same in other libraries), so reuse LOCAL_EXPORT_C_INCLUDES,

dened previously:

...

include $(CLEAR_VARS)

LOCAL_MODULE:= box2d_static

LOCAL_SRC_FILES:= $(BOX2D_CPP)

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)

LOCAL_C_INCLUDES := $(LOCAL_EXPORT_C_INCLUDES)

...

5. Finally, request Box2D module compilaon as a stac library, as follows:

...

include $(BUILD_STATIC_LIBRARY)

...

6. The same process can be repeated to build a shared library by selecng

a dierent module name and invoking $(BUILD_SHARED_LIBRARY), instead:

...

include $(CLEAR_VARS)

LOCAL_MODULE:= box2d_shared

LOCAL_SRC_FILES:= $(BOX2D_CPP)

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)

LOCAL_C_INCLUDES := $(LOCAL_EXPORT_C_INCLUDES)

include $(BUILD_SHARED_LIBRARY)

Android.mk is provided in Chapter09/Library/

Box2D_v2.2.1_android.

7. Open DroidBlaster Android.mk and link against box2d_static, by appending it to

LOCAL_STATIC_LIBRARIES. Provide its directory with direcve import-module.

Remember that modules are found, thanks to the NDK_MODULE_PATH variable,

which points by default to ${ANDROID_NDK}/sources:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

Chapter 9

[ 341 ]

LS_CPP=$(subst $(1)/,,$(wildcard $(1)/*.cpp))

LOCAL_MODULE := droidblaster

LOCAL_SRC_FILES := $(call LS_CPP,$(LOCAL_PATH))

LOCAL_LDLIBS := -landroid -llog -lEGL -lGLESv1_CM -lOpenSLES

LOCAL_STATIC_LIBRARIES:=android_native_app_glue png boost_thread \

box2d_static

include $(BUILD_SHARED_LIBRARY)

$(call import-module,android/native_app_glue)

$(call import-module,libpng)

$(call import-module,boost)

$(call import-module,box2d)

8. Oponally, acvate include le resoluon for Box2D (as seen in Chapter 2, Creang,

Compiling, and Deploying Nave Projects). To do so, in Eclipse Project properes,

go to secon C/C++ General/Paths and Symbols and then the Includes tab, and

add Box2d directory ${env_var:ANDROID_NDK}/sources/box2d.

9. Launch DroidBlaster compilaon. Box2D gets compiled without errors.

Now, let's compile Irrlicht. Irrlicht is currently not supporng Android in its ocial branch.

The iPhone version, which implements an OpenGL ES driver, is sll on a separate branch

(and does not include Android support). However, it is possible to adapt this branch to

make it work with Android (let's say, in a few hours, for experienced programmers).

But there is another soluon: an Android fork iniated by developers from IOPixels (see

http://www.iopixels.com/). It is ready to compile with the NDK and takes advantage

of a few opmizaons. It works quite well, but is not as up-to-date as the iPhone branch.

10. Check out the Irrlicht for Android repository, from Gitorious. This repository can

be found at http://girotious.org/irrlichtandroid/irrlichtandroid.

To do so, install GIT (git package, on Linux) and execute the following command:

> git clone git://gitorious.org/irrlichtandroid/irrlichtandroid.git

The Irrlicht archive is provided with this book, in

directory Chapter09/Library.

11. The repository is on the disk. Move it to ${ANDROID_NDK}/sources and name

it irrlicht.

Porng exisng libraries to Android

[ 342 ]

12. The main directory contains a ready-to-use Android project that makes use of JNI

to communicate with Irrlicht on the nave side. Instead, we are going to adapt this

package to make use of NDK R5 nave acvies.

13. Go to ${ANDROID_NDK}/sources/irrlicht/project/jni and open

Android.mk.

14. Again, makele starts with a $(call my-dir) direcve, to save the current path,

and $(CLEAR_VARS), to erase any pre-exisng values:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

...

15. Aer that, we dene all the source les to compile. And there are lots of them!

Nothing needs to be changed, apart from the Android variable. Indeed, this port

of Irrlicht communicates with a Java applicaon through JNI and gives you some

places to append your own simulaon code.

But, what we want is to compile Irrlicht as a module. So, let's get rid of the useless

JNI binding and rely on the client applicaon for EGL inializaon. Update the

ANDROID direcve to keep only:

importgl.cpp, which gives the opon to bind dynamically to GLES runme.

CIrrDeviceAndroid.cpp, which is an empty stub. It delegates EGL

inializaon to the client. In our case, it is going to be performed by our

GraphicsService:

...

IRRMESHLOADER = CBSPMeshFileLoader.cpp CMD2MeshFileLoader.cpp ...

...

ANDROID = importgl.cpp CIrrDeviceAndroid.cpp

...

16. Then comes the module denion. Variable LOCAL_ARM_MODE can be removed, as

these sengs will be set globally, in our own applicaon, with the Application.

mk le. Of course, it is not forbidden to use a custom seng when needed:

...

LOCAL_MODULE := irrlicht

#LOCAL_ARM_MODE := arm

...

Chapter 9

[ 343 ]

17. Remove the -03 ag from LOCAL_CFLAGS, in the original le. This opon species

the level of opmizaon (here, aggressive). However, it can be set up at applicaon

level too.

ANDROID_NDK ag is specic to this Irrlicht port and is necessary to set up OpenGL.

It works in conjuncon with DISABLE_IMPORTGL, which disables the dynamic

loading of the OpenGL ES system library, at runme. This would be useful if we

wanted to let users choose the renderer at runme (for example, to allow

selecng GLES 2.0 renderer). In that case, the GLES 1 system library would

not be loaded uselessly:

...

LOCAL_CFLAGS := -DANDROID_NDK -DDISABLE_IMPORTGL

LOCAL_SRC_FILES := $(IRRLICHT_CPP)

...

18. Insert LOCAL_EXPORT_C_INCLUDES and LOCAL_C_INCLUDES, to indicate

which include directory to use for library compilaon and which one client

applicaons need. The same goes for linked libraries (LOCAL_EXPORT_LDLIBS

and LOCAL_LDLIBS). Keep only GLESv1_CM. The Irrlicht source folder, which

contains include les needed during Irrlicht compilaon only, is not appended

to the export ags:

...

LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/../include \

$(LOCAL_PATH)/libpng

LOCAL_C_INCLUDES := $(LOCAL_EXPORT_C_INCLUDES) $(LOCAL_PATH)

LOCAL_EXPORT_LDLIBS := -lGLESv1_CM -lz -ldl –llog

LOCAL_LDLIBS := $(LOCAL_EXPORT_LDLIBS)

...

19. Finally, modify Irrlicht to compile as a stac library. We could also compile it as a

shared library. But, because of Irrlicht's size aer compilaon, stac mode is advised.

In addion, it is going to be linked with DroidBlaster.so only:

...

include $(BUILD_STATIC_LIBRARY)

Android.mk is provided in Chapter09/Library/

irrlicht_android.

20. Now, we need to congure what parts of Irrlicht we want to keep and which part we

are not interested in. Indeed, size is an important maer with mobile development,

and the raw Irrlicht library is actually more than 30mb.

Porng exisng libraries to Android

[ 344 ]

As we are basically going to read OBJ meshes and PNG les and display them with

GLES 1.1, everything else can be deacvated. To do so, use #undef direcves in

${ANDROID_NDK}/irrlicht/project/include/IrrCompileConfig.h,

and keep only a few #define where needed:

Target Android with GLES1 only (no GLES 2 or soware renderer).

DroidBlaster requires only non-compressed les read from the le system:

#define _IRR_COMPILE_WITH_ANDROID_DEVICE_

#define _IRR_COMPILE_WITH_OGLES1_

#define _IRR_OGLES1_USE_EXTPOINTER_

#define _IRR_MATERIAL_MAX_TEXTURES_ 4

#define __IRR_COMPILE_WITH_MOUNT_ARCHIVE_LOADER_

Irrlicht embeds a few libraries of its own, such as, libpng, lijpeg,

and so on:

#define _IRR_COMPILE_WITH_OBJ_WRITER_

#define _IRR_COMPILE_WITH_OBJ_LOADER_

#define _IRR_COMPILE_WITH_PNG_LOADER_

#define _IRR_COMPILE_WITH_PNG_WRITER_

#define _IRR_COMPILE_WITH_LIBPNG_

#define _IRR_USE_NON_SYSTEM_LIB_PNG_

#define _IRR_COMPILE_WITH_ZLIB_

#define _IRR_USE_NON_SYSTEM_ZLIB_

#define _IRR_COMPILE_WITH_ZIP_ENCRYPTION_

#define _IRR_COMPILE_WITH_BZIP2_

#define _IRR_USE_NON_SYSTEM_BZLIB_

#define _IRR_COMPILE_WITH_LZMA_

Debug mode can be undef when a applicaon gets released:

#define _DEBUG

The modied IrrCompileConfig.h is provided with this book,

in directory Chapter09/Library/irrlicht_android.

21. Finally, append Irrlicht library to DroidBlaster. We need to remove libpng from

LOCAL_LDLIBS because, from now, DroidBlaster is going to use Irrlicht's libpng,

instead of the one we compiled (which is too recent for Irrlicht):

...

LOCAL_STATIC_LIBRARIES:=android_native_app_glue png boost_thread \

box2d_static irrlicht

Chapter 9

[ 345 ]

include $(BUILD_SHARED_LIBRARY)

$(call import-module,android/native_app_glue)

$(call import-module,libpng)

$(call import-module,boost)

$(call import-module,box2d)

$(call import-module,irrlicht/project/jni)

22. Oponally, acvate include le resoluon for Irrlicht (as done with Box2D

previously). The directory is ${env_var:ANDROID_NDK}/sources/irrlicht.

23. Launch compilaon and watch Irrlicht geng compiled. It may take quite some me!

What just happened?

We have compiled two open source libraries with the Android NDK, thus reusing the many

wheels already created by the community! We will see, in next chapter, how to develop code

with them. There are two main steps involved when porng a library to Android:

1. Adapng library code to Android if necessary.

2. Wring build scripts (that is, makeles) to compile code with the NDK toolchain.

The rst task is generally necessary for libraries accessing system libraries, such as Irrlicht with

OpenGL ES. It is obviously the hardest and most non-trivial task. In that case, always consider:

Making sure required libraries exist. If not, port them before. For instance, the main

Irrlicht branch cannot be used on Android because renderers are only DirectX and

OpenGL (not ES). Only the iPhone branch provides a GLES renderer.

Looking for the main conguraon include le. One is oen provided (such as

IrrCompileConfig.h for Irrlicht) and is a good place to tweak enabled/disabled

features or remove unwanted dependencies.

Giving aenon to system-related macros (that is, #ifdef _LINUX ...), which

are one of the rst places to change in code. Generally, one will need to dene

macros such as _ANDROID_ and insert them where appropriate.

Commenng non-essenal code, at least to check if the library can compile and its

core features work.

The second task, building scripts, is easier, although tedious. You should choose building the

import module dynamically, when compiling your applicaon, as opposed to a prebuilt library,

like we did with Boost. Indeed, on-demand compilaon allows tweaking compilaon ags on

all included libraries (like opmizaon ags or ARM mode) from your main Application.mk

project le.

Porng exisng libraries to Android

[ 346 ]

Prebuilt libraries are only interesng to redistribute binaries, without delivering code, or

to use a custom build system. In the laer case, the NDK toolchain is used in the so-called

standalone mode (that is, Do It Yourself mode!) detailed in the Android NDK documentaon.

But, the default ndk-build command is, of course, considered a beer pracce, to make

future evoluons simpler.

Libraries are produced in <PROJECT_DIR>/libs. Intermediate binary les are available in

<PROJECT_DIR>/obj. Module size in the laer place is quite impressive. That would not

be viable if NDK toolchain was not stripping them when producing nal APK. Stripping is the

process of discarding unnecessary symbols from binaries. Combined with stac linking, this

reduces the size of DroidBlaster binaries from 60 MB to just 3 MB.

GCC optimization levels

There are 5 main opmizaon levels in GCC:

1. -O0: It disables any opmizaon. This is automacally set by the NDK when

APP_OPTIM is set to debug.

2. -O1: It allows basic opmizaons without increasing compilaon me too much.

These opmizaons do not require any speed-space tradeos, which mean that

they produce faster code without increasing executable size.

3. -O2: It allows advanced opmizaon (including -O1), but at the expense of

compilaon me. Like –O1, these opmizaons do not require speed-space

tradeos. This is the default level when APP_OPTIM is set to the release opon,

when releasing an applicaon.

4. -O3: To perform aggressive opmizaons (including -O2), which can increase

executable size, such as funcon inlining. This is generally protable, but

somemes, counterproducve (for example, increasing memory usage can also

increase cache misses).

5. -Os: To opmize compiled code size (a subset of –O2) before speed.

Although -O2 is generally the way to go for release mode, -O3 should also be considered

for performance crical code. -0 ags being just shortcuts for the various GCC opmizaon

ags, enabling –O2 and with addional ne-grain ags (for example, -finline-

functions) is an opon. Anyway, the best way to nd the best choice is sll performing

benchmarking! To get more informaon about the numerous GCC opmizaon opons,

have a look at http://gcc.gnu.org/.

Mastering Makeles

Android makeles are an essenal piece of the NDK building process. Thus, it is important

to understand the way they work, to build and manage a project properly.

Chapter 9

[ 347 ]

Makele variables

Compilaon sengs are dened though a set of predened NDK variables. We have already

seen the three most important ones: LOCAL_PATH, LOCAL_MODULE, and LOCAL_SRC_FILES.

But many others exist. We can dierenate four types of variables, each with a dierent prex:

LOCAL_, APP_, NDK_, and PRIVATE_.

APP_ variables refer to applicaon-wide opons and are set in Application.mk

LOCAL_ variables are dedicated to individual module compilaon and are dened

in Android.mk les

NDK_ are internal variables that usually refer to environment variables (for example,

NDK_ROOT, NDK_APP_CFLAGS or NDK_APP_CPPFLAGS)

PRIVATE_ prexed variables are for NDK internal use only

Here is an almost exhausve list:

LOCAL_PATH To specify the source les, root locaon. Must be

dened before include $(CLEAR_VARS).

LOCAL_MODULE To dene module name.

LOCAL_MODULE_FILENAME

To override default name of the compiled module,

that is,

lib<module name>.so for shared libraries

lib<module name>.a for stac libraries.

No custom le extensions can be specied, so that .so

or.a remains appended.

LOCAL_SRC_FILES To dene source les to compile, each separated by a

space and relave to LOCAL_PATH.

LOCAL_C_INCLUDES

To specify header le directories for both C and

C++ languages. The directory can be relave to the

${ANDROID_NDK} directory, but unless you need

to include a specic NDK le, you are advised to use

absolute path (which can be built from Makele

variables such as $(LOCAL_PATH)).

LOCAL_CPP_EXTENSION

To change default C++ le extension that is.cpp (for

example, cc or cxx). Extension is necessary for GCC to

discriminate between les, according to their language.

LOCAL_CFLAGS,

LOCAL_CPPFLAGS,

LOCAL_LDLIBS

To specify any opons, ags, or macro denions, for

compilaon and linking. The rst one works for both

C and C++, the second one is for C++ only, and the last

one is for the linker.

Porng exisng libraries to Android

[ 348 ]

LOCAL_SHARED_LIBRARIES,

LOCAL_STATIC_LIBRARIES

To declare a dependency with other modules

(not system libraries), shared and stac modules,

respecvely.

LOCAL_ARM_MODE,

LOCAL_ARM_NEON,

LOCAL_DISABLE_NO_

EXECUTE,

LOCAL_FILTER_ASM

Advanced variables dealings with processors and

assembler/binary code generaon. They are not

necessary for most programs.

LOCAL_EXPORT_CFLAGS,

LOCAL_EXPORT_CPPFLAGS,

LOCAL_EXPORT_LDLIBS

To dene addional opons or ags in import modules

that should be appended to clients opons. For

example, if a module A denes

LOCAL_EXPORT_LDLIBS := -llog

because it needs an Android logging module, then

a module B that depends on A will be automacally

linked to –llog.

LOCAL_EXPORT_ variables are not used when

compiling the module that exports them. If required,

they also need to be specied in their LOCAL

counterpart.

Makele Instructions

Although these advanced features are marginally needed, Makele is a real language with

programming instrucons and funcons. First, know that makeles can be broken down into

several sub-makeles, included with the instrucon include.

Variable inializaon comes in two avours:

Simple aectaon: This expands variables at the me that they are inialised.

Recursive aectaon: This re-evaluates the aected expression, each me it is

called.

The following condional and loop instrucons are available: ifdef/endif, ifeq/endif,

ifndef/endif, for…in/do/done. For example, to display a message only when a variable

is dened, do:

ifdef my_var

# Do something...

endif

Chapter 9

[ 349 ]

More advanced stu, such as funconal if, and, or, are at your disposal, but are rarely

used. Make also provides some useful built-in funcons:

$(info <message>)

Allows prinng messages to the standard output. This is the

most essenal tool when wring makeles! Variables inside

informaon messages are allowed.

$(warning <message>),

$(error <message>)

Allows prinng a warning or a fatal error that stops

compilaon. These messages can be parsed by Eclipse.

$(foreach <variable>,

<list>, <operation>)

To perform an operaon on a list of variables. Each element

of the list is expanded in the rst argument variable, before

the operaon is applied on it.

$(shell <command>)

To execute a command outside of Make. This brings all the

power of Unix Shell into Makeles but is heavily system-

dependent. Avoid it if possible.

$(wildcard <pattern>) Select les and directory names according to a paern.

$(call <function>)

Allows evaluang a funcon or macro. One macro we

have seen is my-dir, which returns the directory path

of the last executed Makele. This is why LOCAL_PATH

:= $(call my-dir) is systemacally wrien at the

beginning of each Android.mk le, to save in the current

Makele directory.

With the call direcve, custom funcons can easily be wrien. These funcons look

somewhat similar to recursively aected variables, except that arguments can be dened:

$(1) for rst argument, $(2) for second argument, and so on. A call to a funcon can be

performed in a single line:

my_function=$(<do_something> ${1},${2})

$(call my_function,myparam)

Strings and les manipulaon funcons are available too:

$(join <str1>, <str2>) Concatenates two strings.

$(subst <from>,

<replacement>,<string>),

$(patsubst <pattern>,

<replacement>,<string>)

Replaces each occurrence of a substring by another.

The second one is more powerful, because it allows

using paerns (which must start with "%").

Porng exisng libraries to Android

[ 350 ]

$(filter <patterns>,

<text>)

$(filter-out <patterns>,

<text>)

Filter strings from a text matching paerns. This is

useful for ltering les. For example, the following

line lters any C le:

$(lter %.c, $(my_source_list))

$(strip <string>) Removes any unnecessary whitespace.

$(addprefix

<prefix>,<list>),

$(addsuffix <suffix>,

<list>)

Append a prex and sux, respecvely, to each

element of the list, each element being separated by

a space.

$(basename <path1>,

<path2>, ...)

Returns a string from which le extensions are

removed.

$(dir <path1>, <path2>),

$(notdir <path1>,

<path2>)

Extracts respecvely the directory and the lename

in a path, respecvely

$(realpath <path1>,

<path2>, ...),

$(abspath <path1>,

<path2>, ...)

Return both canonical paths of each path argument,

except that the second one does not evaluate

symbolic links.

This is just really an overview of what Makeles are capable of. For more informaon, refer

to the full Makele documentaon, available at http://www.gnu.org/software/make/

manual/make.html. If you are allergic to Makeles, have a look at CMake. CMake is a

simplied Make system, already building many open source libraries on the market. A port

of CMake on Android is available at http://code.google.com/p/android-cmake.

Have a go hero – mastering Makeles

We can play in a variety of ways with Makeles:

Try the aectaon operator. For example, write down the following piece of code

which uses the = operator in your Android.mk le:

my_value := Android

my_message := I am an $(my_value)

$(info $(my_message))

my_value := Android eating an apple

$(info $(my_message))

Chapter 9

[ 351 ]

Watch the result when launching compilaon. Then do the same using =.Print

current opmizaon mode. Use APP_OPTIM and internal variable, NDK_APP_

CFLAGS, and observe the dierence between release and debug modes:

$(info Optimization level: $(APP_OPTIM) $(NDK_APP_CFLAGS))

Check that variables are properly dened, for example:

ifndef LOCAL_PATH

$(error What a terrible failure! LOCAL_PATH not defined...)

endif

Try to use the foreach instrucon to print the list of les and directories

inside the project's root directory and its jni folder (and make sure to use

recursive aectaon):

ls = $(wildcard $(var_dir))

dir_list := . ./jni

files := $(foreach var_dir, $(dir_list), $(ls))

Try to create a macro to log a message to the standard output and its me:

log=$(info $(shell date +'%D %R'): $(1))

$(call log,My message)

Finally, test the my-dir macro behaviour, to understand why LOCAL_PATH :=

$(call my-dir) is systemacally wrien at the beginning of each Android.mk:

$(info MY_DIR =$(call my-dir))

include $(CLEAR_VARS)

$(info MY_DIR =$(call my-dir))

Summary

The present chapter introduced a fundamental aspect of the NDK: portability. Thanks to the

recent improvements in the building toolchain, the Android NDK can now take advantage

of the vast C/C++ ecosystem. It unlocks the door of a producve environment where code is

shared with other plaorms with the aim of creang new cung-edge applicaons eciently.

More specically, we learnt how to enable, include, and compile STL and Boost and use them

in our own code. We also enabled excepons and RTTI, and selected the appropriate STL

implementaon. Then, we ported Open Source libraries to Android. Finally, we discovered

how to write makeles with advanced instrucons and features.

In the next chapter, these foundaons will allow us to integrate a collision system and to

develop a new 3D graphics system.

Towards Professional Gaming

We have seen in the previous chapter how to port third-party libraries to

Android. More specically, we have compiled two of them: Box2D and Irrlicht.

In this chapter, we are going one step further by implemenng them concretely

in our sample applicaon DroidBlaster. This is the outcome of all the eort

made and all the stu learned unl now. This chapter highlights the path

toward the concrete realizaon of your own applicaon. Of course, there

is sll a very long way to go… but if the slope is steep, the road is straight!

By the end of this chapter, you should be able to do the following:

Simulate physics and handle collisions with Box2D

Display 3D graphics with Irrlicht

Simulating physics with Box2D

We have handled collisions or physics and with good cause! This is a rather complex subject,

involving maths, numerical integraon, soware opmizaon, and so on. To answer these

dicules, physics engine have been invented on the model of 3D engine, and Box2D is one

of them. This open source engine, iniated by Erin Cao in 2006, can simulate rigid body

movements and collisions in a 2D environment. Bodies are the essenal element of Box2D

and are characterized by:

A geometrical shape (polygons, circles, and so on)

Physics properes (such as density, fricon, restuon, and so on)

Movement constraints and joints (to link bodies together and restrict

their movement)

Towards Professional Gaming

[ 354 ]

All these bodies are orchestrated inside a World, which steps simulaon according to me.

In previous chapters, we have created GraphicsService, a SoundService, and

InputService. This me, let's implement PhysicsService with Box2D.

Project DroidBlaster_Part9-3 can be used as a starng point for

this part. The resulng project is provided with this book under

the name DroidBlaster_Part10-Box2D.

Time for action – simulating physics with Box2D

Let's encapsulate Box2D simulaon in a dedicated service rst:

1. First, create jni/PhysicsObject.hpp and insert Box2D main include le. Class

PhysicsObject exposes a locaon and a collision ag publicly. It holds various

Box2D properes dening a physical enty:

A reusable body denion to dene how to simulate a body

(stac, with rotaons).

A body to represent a body instance in the simulated world.

A shape to detect collisions. Here use a circle shape.

A xture to bind a shape to a body and dene a few physics properes.

The class PhysicsObject is set up with initialize() and refreshed with

update() aer each simulaon step. Method createTarget() will help us create

a joint for the ship.

#ifndef PACKT_PHYSICSOBJECT_HPP

#define PACKT_PHYSICSOBJECT_HPP

#include "PhysicsTarget.hpp"

#include "Types.hpp"

#include <boost/smart_ptr.hpp>

#include <Box2D/Box2D.h>

#include <vector>

namespace packt {

class PhysicsObject {

public:

typedef boost::shared_ptr<PhysicsObject> ptr;

typedef std::vector<ptr> vec; typedef vec::iterator vec_it;

public:

PhysicsObject(uint16 pCategory, uint16 pMask,

Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >Downloa d f r o m W o w ! e B o o k < w w w.woweb o o k . c o m >

Chapter 10

[ 355 ]

int32_t pDiameter, float pRestitution, b2World* pWorld);

PhysicsTarget::ptr createTarget(float pFactor);

void initialize(float pX, float pY,

float pVelocityX, float pVelocityY);

void update();

bool mCollide;

Location mLocation;

private:

b2World* mWorld;

b2BodyDef mBodyDef; b2Body* mBodyObj;

b2CircleShape mShapeDef; b2FixtureDef mFixtureDef;

};

}

#endif

2. Implement jni/PhysicsObject.cpp constructor to inialize all Box2D properes.

The body denion describes a dynamic body (as opposed to stac), awake (that

is, acvely simulated by Box2D), and which cannot rotate (a property especially

important for polygon shapes, meaning that it is always poinng upward).

Also note how we save a PhysicsObject self reference in userData eld, in order

to access it later inside Box2D callbacks

3. Dene body shape, which we approximate to a box. Box2D requires half dimension,

from object's center to its borders.

#include "PhysicsObject.hpp"

#include "Log.hpp"

namespace packt {

PhysicsObject::PhysicsObject(uint16 pCategory, uint16 pMask,

int32_t pDiameter, float pRestitution, b2World* pWorld) :

mLocation(), mCollide(false), mWorld(pWorld),

mBodyDef(), mBodyObj(NULL), mShapeDef(), mFixtureDef() {

mBodyDef.type = b2_dynamicBody;

mBodyDef.userData = this;

mBodyDef.awake = true;

mBodyDef.fixedRotation = true;

mShapeDef.m_p = b2Vec2_zero;

mShapeDef.m_radius = pDiameter / (2.0f * SCALE_FACTOR);

...

Towards Professional Gaming

[ 356 ]

4. Body xture is the glue which brings together body denion, shape, and also physical

properes. We also use it to set body category and mask. This allows us to lter

collisions between objects according to their category (for instance, asteroids must

collide with the ship but not between themselves). There is one category per bit.

Finally, eecvely instanate your body inside the Box2D physical world:

...

mFixtureDef.shape = &mShapeDef;

mFixtureDef.density = 1.0f;

mFixtureDef.friction = 0.0f;

mFixtureDef.restitution = pRestitution;

mFixtureDef.filter.categoryBits = pCategory;

mFixtureDef.filter.maskBits = pMask;

mFixtureDef.userData = this;

mBodyObj = mWorld->CreateBody(&mBodyDef);

mBodyObj->CreateFixture(&mFixtureDef);

mBodyObj->SetUserData(this);

}

...

5. Then take care of mouse joint creaon in createTarget().

When PhysicsObject is inialized, coordinates are converted from DroidBlaster

referenal to Box2D one. Indeed, Box2D performs beer with smaller coordinates.

When Box2D has nished simulang, each PhysicsObject instance converts

coordinates computed by Box2D back into DroidBlaster coordinates referenal:

...

PhysicsTarget::ptr PhysicsObject::createTarget(float pFactor)

{

return PhysicsTarget::ptr(

new PhysicsTarget(mWorld, mBodyObj, mLocation,

pFactor));

}

void PhysicsObject::initialize(float pX, float pY,

float pVelocityX, float pVelocityY) {

mLocation.setPosition(pX, pY);

b2Vec2 lPosition(pX / SCALE_FACTOR, pY / SCALE_FACTOR);

mBodyObj->SetTransform(lPosition, 0.0f);

mBodyObj->SetLinearVelocity(b2Vec2(pVelocityX,

pVelocityY));

}

Chapter 10

[ 357 ]

void PhysicsObject::update() {

mLocation.setPosition(

mBodyObj->GetPosition().x * SCALE_FACTOR,

mBodyObj->GetPosition().y * SCALE_FACTOR);

}

6. Now, create jni/PhysicsService.hpp header and again insert the Box2D

include le. Make PhysicsService inherit from b2ContactListener. A contact

listener gets noed about new collisions each me the simulaon is updated. Our

PhysicsService inherits one of its method named BeginContact().

Dene constants and member variables. Iteraon constants determine the

simulaon accuracy. Variable mWorld represents the whole Box2D simulaon

which contains all the physical bodies we are going to create:

#ifndef PACKT_PHYSICSSERVICE_HPP

#define PACKT_PHYSICSSERVICE_HPP

#include "PhysicsObject.hpp"

#include "TimeService.hpp"

#include "Types.hpp"

#include <Box2D/Box2D.h>

namespace packt {

class PhysicsService : private b2ContactListener {

public:

PhysicsService(TimeService* pTimeService);

status update();

PhysicsObject::ptr registerEntity(uint16 pCategory,

uint16 pMask, int32_t pDiameter, float pRestitution);

private:

void BeginContact(b2Contact* pContact);

private:

TimeService* mTimeService;

PhysicsObject::vec mColliders;

b2World mWorld;

static const int32_t VELOCITY_ITER = 6;

static const int32_t POSITION_ITER = 2;

};

}

#endif

Towards Professional Gaming

[ 358 ]

7. In the jni/PhysicsService.cpp source le, write PhysicsService constructor.

Inialize the world, seng the rst parameter to a zero vector (type b2vec). This

vector represents the gravity force, which is not necessary in DroidBlaster. Finally,

simulaon is stepped, PhysicsService gets noed through callbacks.

Destroy Box2D resources in the destructor. Box2D uses its own internal (de)allocator.

Also implement registerEntity() to encapsulate physics object creaon:

#include "PhysicsService.hpp"

#include "Log.hpp"

namespace packt {

PhysicsService::PhysicsService(TimeService* pTimeService) :

mTimeService(pTimeService),

mColliders(), mWorld(b2Vec2_zero) {

mWorld.SetContactListener(this);

}

PhysicsObject::ptr PhysicsService::registerEntity(

uint16 pCategory, uint16 pMask, int32_t pDiameter,

float pRestitution) {

PhysicsObject::ptr lCollider(new PhysicsObject(pCategory,

pMask, pDiameter, pRestitution, &mWorld));

mColliders.push_back(lCollider);

return mColliders.back();

}

...

8. Write the update() method. First, it clears collision ags buered in

BeginContact() during previous iteraon. Then simulaon is performed by calling

Step() with a me period and iteraons constants dene simulaon accuracy. Finally,

PhysicsObject is updated (that is, locaon extracted from Box2D into our own

Location object) according to simulaon results. Box2D is going to handle mainly

collisions and simple movements. So xing velocity and posion iteraons to 6 and 2,

respecvely, is sucient.

...

status PhysicsService::update() {

PhysicsObject::vec_it iCollider = mColliders.begin();

for (; iCollider < mColliders.end() ; ++iCollider) {

(*iCollider)->mCollide = false;

}

Chapter 10

[ 359 ]

// Updates simulation.

float lTimeStep = mTimeService->elapsed();

mWorld.Step(lTimeStep, VELOCITY_ITER, POSITION_ITER);

// Caches the new state.

iCollider = mColliders.begin();

for (; iCollider < mColliders.end() ; ++iCollider) {

(*iCollider)->update();

}

return STATUS_OK;

}

...

9. The method BeginContact() is a callback inherited by b2ContactListener

to nofy about new collisions between bodies, two at a me (named A and B).

Event informaon is stored in a b2contact structure, which contains various

properes, such as fricon and restuon, and the two bodies involved through

their xture, which themselves contain a reference to our own PhysicsObject

(the UserData property set in GraphicsObject). We can use this link to switch

the PhysicsObject collision ag when Box2D detects one:

...

void PhysicsService::BeginContact(b2Contact* pContact) {

void* lUserDataA = pContact->GetFixtureA()->GetUserData();

if (lUserDataA != NULL) {

((PhysicsObject*)(lUserDataA))->mCollide = true;

}

void* lUserDataB = pContact->GetFixtureB()->GetUserData();

if (lUserDataB != NULL) {

((PhysicsObject*)(lUserDataB))->mCollide = true;

}

10. Finally, create jni/PhysicsTarget.hpp to encapsulate Box2D mouse joints.

The ship will follow the direcon specied in setTarget(). To do so, we need a

mulplier (mFactor) to simulate a target point from the input service output vector.

Mouse joints are usually good to simulate dragging eects or for

test purposes. They are easy to use but implemenng a precise

behavior with them is dicult.

#ifndef PACKT_PHYSICSTARGET_HPP

#define PACKT_PHYSICSTARGET_HPP

Towards Professional Gaming

[ 360 ]

#include "Types.hpp"

#include <boost/smart_ptr.hpp>

#include <Box2D/Box2D.h>

namespace packt {

class PhysicsTarget {

public:

typedef boost::shared_ptr<PhysicsTarget> ptr;

public:

PhysicsTarget(b2World* pWorld, b2Body* pBodyObj,

Location& pTarget, float pFactor);

void setTarget(float pX, float pY);

private:

b2MouseJoint* mMouseJoint;

float mFactor; Location& mTarget;

};

}

#endif

11. The source counterpart is jni/PhysicsTarget.cpp to encapsulate a

Box2D mouse joint. The ship will follow the direcon specied in setTarget()

each frame.

#include "PhysicsTarget.hpp"

#include "Log.hpp"

namespace packt {

PhysicsTarget::PhysicsTarget(b2World* pWorld, b2Body* pBodyObj,

Location& pTarget, float pFactor):

mFactor(pFactor), mTarget(pTarget) {

b2BodyDef lEmptyBodyDef;

b2Body* lEmptyBody = pWorld->CreateBody(&lEmptyBodyDef);

b2MouseJointDef lMouseJointDef;

lMouseJointDef.bodyA = lEmptyBody;

lMouseJointDef.bodyB = pBodyObj;

lMouseJointDef.target = b2Vec2(0.0f, 0.0f);

lMouseJointDef.maxForce = 50.0f * pBodyObj->GetMass();

lMouseJointDef.dampingRatio = 1.0f;

lMouseJointDef.frequencyHz = 3.5f;

mMouseJoint = (b2MouseJoint*)

pWorld->CreateJoint(&lMouseJointDef);

}

Chapter 10

[ 361 ]

void PhysicsTarget::setTarget(float pX, float pY) {

b2Vec2 lTarget((mTarget.mPosX + pX * mFactor) / SCALE_FACTOR,

(mTarget.mPosY + pY * mFactor) / SCALE_FACTOR);

mMouseJoint->SetTarget(lTarget);

}

12. Finally, add the PhysicsService to jni/Context.hpp like all the other

services created in previous chapters.

We can now go back to our asteroids and simulate them with our new

physics service.

13. In jni/Asteroid.hpp, replace locaon and speed by PhysicsObject instance:

...

#include "PhysicsService.hpp"

#include "PhysicsObject.hpp"

...

namespace dbs {

class Asteroid {

...

private:

...

packt::GraphicsSprite* mSprite;

packt::PhysicsObject::ptr mPhysics;

};

}

14. Makes use of this new physics object in jni/Asteroid.cpp source le. Physics

properes are registered with a category and mask. Here, Asteroids are declared

as belonging to category 1 (0X1 in hexadecimal notaon) and only bodies in

group 2 (0X2 in hexadecimal) are considered when evaluang collisions.

To spawn an asteroid, replace speed with the noon of velocity (expressed in m/s).

Because asteroid direcon will change when a collision occurs, asteroids are spawn

when they go outside the main area in update():

#include "Asteroid.hpp"

#include "Log.hpp"

namespace dbs {

Asteroid::Asteroid(packt::Context* pContext) :

mTimeService(pContext->mTimeService),

mGraphicsService(pContext->mGraphicsService) {

mPhysics = pContext->mPhysicsService->registerEntity(

Towards Professional Gaming

[ 362 ]

0X1, 0x2, 64, 1.0f);

mSprite = pContext->mGraphicsService->registerSprite(

mGraphicsService->registerTexture(

"/sdcard/droidblaster/asteroid.png"),

64, 64, &mPhysics->mLocation);

}

void Asteroid::spawn() {

const float MIN_VELOCITY = 1.0f, VELOCITY_RANGE=19.0f;

const float MIN_ANIM_SPEED = 8.0f, ANIM_SPEED_RANGE=16.0f;

float lVelocity = -(RAND(VELOCITY_RANGE) + MIN_VELOCITY);

float lPosX = RAND(mGraphicsService->getWidth());

float lPosY = RAND(mGraphicsService->getHeight())

+ mGraphicsService->getHeight();

mPhysics->initialize(lPosX, lPosY, 0.0f, lVelocity);

float lAnimSpeed = MIN_ANIM_SPEED + RAND(ANIM_SPEED_RANGE);

mSprite->setAnimation(8, -1, lAnimSpeed, true);

}

void Asteroid::update() {

if ((mPhysics->mLocation.mPosX < 0.0f) ||

(mPhysics->mLocation.mPosX > mGraphicsService->getWidth())||

(mPhysics->mLocation.mPosY < 0.0f) ||

(mPhysics->mLocation.mPosY > mGraphicsService->getHeight()*2)){

spawn();

}

15. Modify the jni/Ship.hpp header le in the same way as asteroids:

...

#include "PhysicsService.hpp"

#include "PhysicsObject.hpp"

#include "PhysicsTarget.hpp"

...

namespace dbs {

class Ship {

...

Chapter 10

[ 363 ]

private:

...

packt::GraphicsSprite* mSprite;

packt::PhysicsObject::ptr mPhysics;

packt::PhysicsTarget::ptr mTarget;

};

}

16. Rewrite jni/Ship.cpp with the new PhysicsObject. Ship is added to category

2 and is marked as colliding with category 1 only (that is, asteroids). Velocity and

movement is enrely managed by Box2D. We can now check in update() if an

asteroid collided:

#include "Ship.hpp"

#include "Log.hpp"

namespace dbs {

Ship::Ship(packt::Context* pContext) :

mInputService(pContext->mInputService),

mGraphicsService(pContext->mGraphicsService),

mTimeService(pContext->mTimeService) {

mPhysics = pContext->mPhysicsService->registerEntity(

0x2, 0x1, 64, 0.0f);

mTarget = mPhysics->createTarget(50.0f);

mSprite = pContext->mGraphicsService->registerSprite(

mGraphicsService->registerTexture(

"/sdcard/droidblaster/ship.png"),

64, 64, &mPhysics->mLocation);

mInputService->setRefPoint(&mPhysics->mLocation);

}

void Ship::spawn() {

mSprite->setAnimation(0, 8, 8.0f, true);

mPhysics->initialize(mGraphicsService->getWidth() * 1 / 2,

mGraphicsService->getHeight() * 1 / 4, 0.0f, 0.0f);

}

void Ship::update() {

mTarget->setTarget(mInputService->getHorizontal(),

mInputService->getVertical());

if (mPhysics->mCollide) {

packt::Log::info("Ship has been touched");

}

Towards Professional Gaming

[ 364 ]

Finally, let's instanate and run our physics service.

17. Modify jni/DroidBlaster.hpp to hold PhysicsService instance:

...

#include "PhysicsService.hpp"

...

namespace dbs {

class DroidBlaster : public packt::ActivityHandler {

...

private:

packt::GraphicsService* mGraphicsService;

packt::InputService* mInputService;

packt::PhysicsService* mPhysicsService;

packt::SoundService* mSoundService;

...

};

}

18. Update PhysicsService each me the game is stepped:

namespace dbs {

...

packt::status DroidBlaster::onStep()

{

...

if (mInputService->update() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

if (mPhysicsService->update() != packt::STATUS_OK) {

return packt::STATUS_KO;

}

return packt::STATUS_OK;

}

...

}

19. Finally, instanate PhysicsService in the applicaon's main method:

...

#include "PhysicsService.hpp"

...

void android_main(android_app* pApplication) {

...

Chapter 10

[ 365 ]

packt::PhysicsService lPhysicsService(&lTimeService);

packt::SoundService lSoundService(pApplication);

packt::Context lContext = { &lGraphicsService, &lInputService,

&lPhysicsService, &lSoundService, &lTimeService };

...

}

What just happened?

We have created a physical simulaon using Box2D physics engine. We have seen how to do

the following:

Dene a physical representaon of enes (ships and asteroids)

Step a simulaon and detect/lter collisions between enes

Extracted simulaon state (that is, coordinates) to feed graphics representaon

The central point of access in Box2D is b2World, which stores a collecon of bodies to

simulate. A Box2D body is composed of the following:

b2BodyDef: This denes the body type (b2_staticBody, b2_dynamicBody, and

so on) and inial properes like its posion, angle (in radians), and so on.

b2Shape: This is used for collision detecon and to derive body mass from its

density and can be a b2PolygonShape, b2CircleShape, and so on

b2FixtureDef: This links together a body shape, a body denion, and its physical

properes, such as density

b2Body: This is a body instance in the world (that is, on per game object), created

from a body denion, a shape, and a xture

Bodies are characterized by a few physical properes:

Shape: This represents a circle in DroidBlaster, although a polygon or box could

also be used.

Density: This is in kg/m2, to compute body mass depending on its shape and size.

Value should be greater or equal to 0.0. A bowling ball has a bigger density than a

soccer ball.

Fricon: This property shows how much a body slides on another (for example, a car

on a road or on an icy path). Values are typically in the range 0.0 to 1.0, where 0.0

implies no fricon and 1.0 means strong fricon.

Restuon: This property shows how much a body reacts to a collision, for example,

a bouncing ball. Value 0.0 means no restuon and 1.0 full restuon.

Towards Professional Gaming

[ 366 ]

When running, bodies are subject to the following:

Forces: This make bodies move linearly.

Torques: This represents rotaonal force applied on a body.

Damping: This is similar to fricon but it does not occur only when a body is in contact

with another. It can be considered as the eect of air fricon slowing down a body.

Box2D is tuned for worlds containing objects at a scale from 0.1 to 10 (unit in meters). When

used outside this range, again numerical approximaon can make simulaon inaccurate.

Thus, it is very necessary to scale coordinates from the Box2D referenal, where object

should to be kept in the (rough) range [0.1, 10] and, to the game or directly to the graphics

referenal. This is where SCALE_FACTOR is used for coordinate transformaon.

Box2D memory management

Box2D uses its own allocators to opmize memory management. So to create

and destroy Box2D objects, one needs to systemacally use the provided

factory methods (CreateX(), DestroyX()). Most of the me, Box2D

will manage memory automacally for you. When an object is destroyed, all

related child objects get destroyed (for instance, the bodies are destroyed

when the world is destroyed). But if you need to get rid of your objects earlier,

and thus manually, then always destroy them.

Android.NDK.Beginner.Guide

Navigation menu

Versions of this User Manual:

Views

Navigation