AccelerometerHandler: Which Side Is Up?

Let’s start with the easiest of all handlers, the AccelerometerHandler. Listing 5-5 shows its code.

Listing 5-5. AccelerometerHandler.java; Performing All the Accelerometer Handling

package com.badlogic.androidgames.framework.impl;

import android.content.Context;
import android.hardware.Sensor;
import android.hardware.SensorEvent;
import android.hardware.SensorEventListener;
import android.hardware.SensorManager;

public class AccelerometerHandler implements SensorEventListener {
    float accelX;
    float accelY;
    float accelZ;
    public AccelerometerHandler(Context context) {
        SensorManager manager = (SensorManager) context
                .getSystemService(Context.SENSOR_SERVICE);
        if (manager.getSensorList(Sensor.TYPE_ACCELEROMETER).size() ! = 0) {
            Sensor accelerometer = manager.getSensorList(
                    Sensor.TYPE_ACCELEROMETER).get(0);
            manager.registerListener(this , accelerometer,
                    SensorManager.SENSOR_DELAY_GAME);
        }
    }
    public void onAccuracyChanged(Sensor sensor, int accuracy) {
        // nothing to do here
    }
    public void onSensorChanged(SensorEvent event) {
        accelX = event.values[0];
        accelY = event.values[1];
        accelZ = event.values[2];
    }
    public float getAccelX() {
        return accelX;
    }
    public float getAccelY() {
        return accelY;
    }
    public float getAccelZ() {
        return accelZ;
    }
}

Unsurprisingly, the class implements the SensorEventListener interface that we used in Chapter 4. The class stores three members by holding the acceleration on each of the three accelerometers’ axes.

The constructor takes a Context, from which it gets a SensorManager instance to set up the event listening. The rest of the code is equivalent to what we did in Chapter 4. Note that if no accelerometer is installed, the handler will happily return zero acceleration on all axes throughout its life. Therefore, we don’t need any extra error-checking or exception-throwing code.

The next two methods, onAccuracyChanged() and onSensorChanged(), should be familiar. In the first method, we don’t do anything, so there’s nothing much to report. In the second one, we fetch the accelerometer values from the provided SensorEvent and store them in the handler’s members. The final three methods simply return the current acceleration for each axis.

Note that we do not need to perform any synchronization here, even though the onSensorChanged() method might be called in a different thread. The Java memory model guarantees that writes and reads, to and from, primitive types such as Boolean, int, or byte are atomic. In this case, it’s OK to rely on this fact since we aren’t doing anything more complex than assigning a new value. We’d need to have proper synchronization if this were not the case (for example, if we did something with the member variables in the onSensorChanged() method).

The Pool Class: Because Reuse Is Good for You!

What’s the worst thing that can happen to us as Android developers? World-stopping garbage collection! If you look at the Input interface definition in Chapter 3, you’ll find the getTouchEvents() and getKeyEvents() methods. These methods return TouchEvent and KeyEvent lists. In our keyboard and touch event handlers, we constantly create instances of these two classes and store them in lists that are internal to the handlers. The Android input system fires many of these events when a key is pressed or a finger touches the screen, so we constantly create new instances that are collected by the garbage collector in short intervals. In order to avoid this, we implement a concept known as instance pooling. Instead of repeatedly creating new instances of a class, we simply reuse previously created instances. The Pool class is a convenient way to implement that behavior. Let’s have a look at its code in Listing 5-7, which is broken up again, containing appropriate commentary.

Listing 5-7. Pool.java; Playing Well with the Garbage Collector

package com.badlogic.androidgames.framework;

import java.util.ArrayList;
import java.util.List;

public class Pool < T > {

Here are the generics: the first thing to recognize is that this is a generically typed class, much like collection classes such as ArrayList or HashMap. Generics allow us to store any type of object in our Pool without having to cast continuously. So what does the Pool class do?

    public interface PoolObjectFactory < T > {
        public T createObject();
    }

An interface called PoolObjectFactory is the first thing defined and is, once again, generic. It has a single method, createObject(), that will return a new object with the generic type of the Pool/PoolObjectFactory instance.

    private final List < T > freeObjects;
    private final PoolObjectFactory < T > factory;
    private final int maxSize;

The Pool class has three members. These include an ArrayList to store pooled objects, a PoolObjectFactory that is used to generate new instances of the type held by the class, and a member that stores the maximum number of objects the Pool can hold. The last bit is needed so our Pool does not grow indefinitely; otherwise, we might run into an out-of-memory exception.

    public Pool(PoolObjectFactory < T > factory, int maxSize) {
        this.factory = factory;
        this.maxSize = maxSize;
        this.freeObjects = new ArrayList < T > (maxSize);
    }

The constructor of the Pool class takes a PoolObjectFactory and the maximum number of objects it should store. We store both parameters in the respective members and instantiate a new ArrayList with the capacity set to the maximum number of objects.

    public T newObject() {
       T object = null ;
       if (freeObjects.isEmpty())
           object = factory.createObject();
       else 
           object = freeObjects.remove(freeObjects.size() - 1);
       return object;
    }

The newObject() method is responsible for either handing us a brand-new instance of the type held by the Pool, via the PoolObjectFactory.newObject() method, or returning a pooled instance in case there’s one in the freeObjectsArrayList. If we use this method, we get recycled objects as long as the Pool has some stored in the freeObjects list. Otherwise, the method creates a new one via the factory.

    public void free(T object) {
        if (freeObjects.size() < maxSize)
            freeObjects.add(object);
    }
}

The free() method lets us reinsert objects that we no longer use. It simply inserts the object into the freeObjects list if it is not yet filled to capacity. If the list is full, the object is not added, and it is likely to be consumed by the garbage collector the next time it executes.

So, how can we use that class? We’ll look at some pseudocode usage of the Pool class in conjunction with touch events.

PoolObjectFactory <TouchEvent> factory = new PoolObjectFactory <TouchEvent> () {
    @Override
    public TouchEvent createObject() {
        return new TouchEvent();
    }
};
Pool <TouchEvent> touchEventPool = new Pool <TouchEvent> (factory, 50);
TouchEvent touchEvent = touchEventPool.newObject();
. . . do something here . . .
touchEventPool.free(touchEvent);

First, we define a PoolObjectFactory that creates TouchEvent instances. Next, we instantiate the Pool by telling it to use our factory and that it should maximally store 50 TouchEvents. When we want a new TouchEvent from the Pool, we call the Pool’s newObject() method. Initially, the Pool is empty, so it will ask the factory to create a brand-new TouchEvent instance. When we no longer need the TouchEvent, we reinsert it into the Pool by calling the Pool’s free() method. The next time we call the newObject() method, we get the same TouchEvent instance and recycle it to avoid problems with the garbage collector. This class is useful in a couple of places. Please note that you must be careful to fully reinitialize reused objects when they’re fetched from the Pool.

KeyboardHandler: Up, Up, Down, Down, Left, Right . . .

The KeyboardHandler must fulfill a couple of tasks. First, it must connect with the View from which keyboard events are to be received. Next, it must store the current state of each key for polling. It must also keep a list of KeyEvent instances that we designed in Chapter 3 for event-based input handling. Finally, it must properly synchronize everything since it will receive events on the UI thread while being polled from our main game loop, which is executed on a different thread. This is a lot of work! As a refresher, we’ll show you the KeyEvent class that we defined in Chapter 3 as part of the Input interface.

public static class KeyEvent {
    public static final int KEY_DOWN = 0;
    public static final int KEY_UP = 1;

    public int type;
    public int keyCode;
    public char keyChar;
}

This class simply defines two constants that encode the key event type along with three members while holding the type, key code, and Unicode character of the event. With this, we can implement our handler.

Listing 5-8 shows the implementation of the handler with the Android APIs discussed earlier and our new Pool class. The listing is broken up by commentary.

Listing 5-8. KeyboardHandler.java: Handling Keys Since 2010

package com.badlogic.androidgames.framework.impl;

import java.util.ArrayList;
import java.util.List;

import android.view.View;
import android.view.View.OnKeyListener;

import com.badlogic.androidgames.framework.Input.KeyEvent;
import com.badlogic.androidgames.framework.Pool;
import com.badlogic.androidgames.framework.Pool.PoolObjectFactory;

public class KeyboardHandler implements OnKeyListener {
    boolean [] pressedKeys = new boolean [128];
    Pool <KeyEvent> keyEventPool;
    List <KeyEvent> keyEventsBuffer = new ArrayList <KeyEvent> ();
    List <KeyEvent> keyEvents = new ArrayList <KeyEvent> ();

The KeyboardHandler class implements the OnKeyListener interface so that it can receive key events from a View. The members are next.

The first member is an array holding 128 Booleans. We store the current state (pressed or not) of each key in this array. It is indexed by the key’s key code. Luckily for us, the android.view.KeyEvent.KEYCODE_XXX constants (which encode the key codes) are all between 0 and 127, so we can store them in a garbage collector–friendly form. Note that by an unlucky accident, our KeyEvent class shares its name with the Android KeyEvent class, of which instances get passed to our OnKeyEventListener.onKeyEvent() method. This slight confusion is only limited to this handler code. As there’s no better name for a key event than “KeyEvent,” we chose to live with this short-lived confusion.

The next member is a Pool that holds the instances of our KeyEvent class. We don’t want to make the garbage collector angry, so we recycle all the KeyEvent objects we create.

The third member stores the KeyEvent instances hat have not yet been consumed by our game. Each time we get a new key event on the UI thread, we add it to this list.

The last member stores the KeyEvents that we return by calling the KeyboardHandler.getKeyEvents(). In the following sections, we’ll see why we have to double-buffer the key events.

    public KeyboardHandler(View view) {
        PoolObjectFactory <KeyEvent> factory = new PoolObjectFactory <KeyEvent> () {
            public KeyEvent createObject() {
                return new KeyEvent();
            }
        };
        keyEventPool = new Pool < KeyEvent > (factory, 100);
        view.setOnKeyListener(this );
        view.setFocusableInTouchMode(true );
        view.requestFocus();
    }

The constructor has a single parameter consisting of the View from which we want to receive key events. We create the Pool instance with a proper PoolObjectFactory, register the handler as an OnKeyListener with the View, and, finally, make sure that the View will receive key events by making it the focused View.

    public boolean onKey(View v, int keyCode, android.view.KeyEvent event) {
        if (event.getAction() == android.view.KeyEvent.ACTION_MULTIPLE)
            return false ;

        synchronized (this ) {
            KeyEvent keyEvent = keyEventPool.newObject();
            keyEvent.keyCode = keyCode;
            keyEvent.keyChar = (char ) event.getUnicodeChar();
            if (event.getAction() == android.view.KeyEvent.ACTION_DOWN) {
                keyEvent.type = KeyEvent.KEY_DOWN;
                if (keyCode > 0 && keyCode < 127)
                    pressedKeys[keyCode] = true ;
            }
            if (event.getAction() == android.view.KeyEvent.ACTION_UP) {
                keyEvent.type = KeyEvent.KEY_UP;
                if (keyCode > 0 && keyCode < 127)
                    pressedKeys[keyCode] = false ;
            }
            keyEventsBuffer.add(keyEvent);
        }
        return false ;
    }

Next, we will discuss our implementation of the OnKeyListener.onKey() interface method, which is called each time the View receives a new key event. We start by ignoring any (Android) key events that encode a KeyEvent.ACTION_MULTIPLE event. These are not relevant in our context. This is followed by a synchronized block. Remember, the events are received on the UI thread and read on the main loop thread, so we have to make sure that none of our members are accessed in parallel.

Within the synchronized block, we first fetch a KeyEvent instance (of our KeyEvent implementation) from the Pool. This will either get us a recycled instance or a brand-new one, depending on the state of the Pool. Next, we set the KeyEvent’s keyCode and keyChar members based on the contents of the Android KeyEvent that were passed to the method. Then, we decode the Android KeyEvent type and set the type of our KeyEvent, as well as the element in the pressedKey array, accordingly. Finally, we add our KeyEvent to the previously defined keyEventBuffer list.

    public boolean isKeyPressed(int keyCode) {
        if (keyCode < 0 || keyCode > 127)
            return false ;
        return pressedKeys[keyCode];
    }

The next method of our handler is the isKeyPressed() method, which implements the semantics of Input.isKeyPressed(). First, we pass in an integer that specifies the key code (one of the Android KeyEvent.KEYCODE_XXX constants) and returns whether that key is pressed or not. We do this by looking up the state of the key in the pressedKey array after some range checking. Remember, we set the elements of this array in the previous method, which gets called on the UI thread. Since we are working with primitive types again, there’s no need for synchronization.

    public List <KeyEvent> getKeyEvents() {
        synchronized (this ) {
            int len = keyEvents.size();
            for (int i = 0; i < len; i++) {
                keyEventPool.free(keyEvents.get(i));
            }
            keyEvents.clear();
            keyEvents.addAll(keyEventsBuffer);
            keyEventsBuffer.clear();
            return keyEvents;
        }
    }
}

The last method of our handler is called getKeyEvents(), and it implements the semantics of the Input.getKeyEvents() method. Once again, we start with a synchronized block and remember that this method will be called from a different thread.

Next, we loop through the keyEvents array and insert all of its KeyEvents into our Pool. Remember, we fetch instances from the Pool in the onKey() method on the UI thread. Here, we reinsert them into the Pool. But isn’t the keyEvents list empty? Yes, but only the first time we invoke that method. To understand why, you have to grasp the rest of the method.

After our mysterious Pool insertion loop, we clear the keyEvents list and fill it with the events in our keyEventsBuffer list. Finally, we clear the keyEventsBuffer list and return the newly filled keyEvents list to the caller. What is happening here?

We’ll use a simple example to illustrate this. First, we’ll examine what happens to the keyEvents and the keyEventsBuffer lists, as well as to our Pool, each time a new event arrives on the UI thread or the game fetches the events in the main thread:

UI thread: onKey() ->
           keyEvents = { }, keyEventsBuffer = {KeyEvent1}, pool = { }
Main thread: getKeyEvents() ->
           keyEvents = {KeyEvent1}, keyEventsBuffer = { }, pool { }
UI thread: onKey() ->
           keyEvents = {KeyEvent1}, keyEventsBuffer = {KeyEvent2}, pool { }
Main thread: getKeyEvents() ->
           keyEvents = {KeyEvent2}, keyEventsBuffer = { }, pool = {KeyEvent1}
UI thread: onKey() ->

           keyEvents = {KeyEvent2}, keyEventsBuffer = {KeyEvent1}, pool = { }

1. We get a new event in the UI thread. There’s nothing in the Pool yet, so a new KeyEvent instance (KeyEvent1) is created and inserted into the keyEventsBuffer list.
2. We call getKeyEvents() on the main thread. getKeyEvents() takes KeyEvent1 from the keyEventsBuffer list and puts it into the keyEvents list that is returns to the caller.
3. We get another event on the UI thread. We still have nothing in the Pool, so a new KeyEvent instance (KeyEvent2) is created and inserted into the keyEventsBuffer list.
4. The main thread calls getKeyEvents() again. Now, something interesting happens. Upon entry into the method, the keyEvents list still holds KeyEvent1. The insertion loop will place that event into our Pool. It then clears the keyEvents list and inserts any KeyEvent into the keyEventsBuffer, in this case, KeyEvent2. We just recycled a key event.
5. Another key event arrives on the UI thread. This time, we have a free KeyEvent in our Pool, which we happily reuse. Incredibly, there’s no garbage collection!

This mechanism comes with one caveat, which is that we have to call KeyboardHandler.getKeyEvents() frequently or the keyEvents list fills up quickly, and no objects are returned to the Pool. Problems can be avoided as long as we remember this.

Touch Handlers

Now it is time to consider fragmentation. In Chapter 4, we revealed that multitouch is only supported on Android versions greater than 1.6. All the nice constants we used in our multitouch code (for example, MotionEvent.ACTION_POINTER_ID_MASK) are not available to us on Android 1.5 or 1.6. We can use them in our code if we set the build target of our project to an Android version that has this API; however, the application will crash on any device running Android 1.5 or 1.6. We want our games to run on all currently available Android versions, so how do we solve this problem?

We employ a simple trick. We write two handlers, one using the single-touch API in Android 1.5, and another using the multitouch API in Android 2.0 and above. This is safe as long as we don’t execute the multitouch handler code on an Android device lower than version 2.0. The VM won’t load the code, and it won’t throw exceptions continuously. All we need to do is find out which Android version the device is running and instantiate the proper handler. You’ll see how this works when we discuss the AndroidInput class. For now, let’s concentrate on the two handlers.

package com.badlogic.androidgames.framework.impl;

import java.util.List;

import android.view.View.OnTouchListener;

import com.badlogic.androidgames.framework.Input.TouchEvent;

public interface TouchHandlerextends OnTouchListener {
    public boolean isTouchDown(int pointer);

    public int getTouchX(int pointer);

    public int getTouchY(int pointer);

    public List <TouchEvent> getTouchEvents();

}

public static class TouchEvent {
    public static final int TOUCH_DOWN = 0;
    public static final int TOUCH_UP = 1;
    public static final int TOUCH_DRAGGED = 2;

    public int type;
    public int x, y;
    public int pointer;
}

package com.badlogic.androidgames.framework.impl;

import java.util.ArrayList;
import java.util.List;

import android.view.MotionEvent;
import android.view.View;
import com.badlogic.androidgames.framework.Pool;

import com.badlogic.androidgames.framework.Input.TouchEvent;
import com.badlogic.androidgames.framework.Pool.PoolObjectFactory;

public class SingleTouchHandler implements TouchHandler {
    boolean isTouched;
    int touchX;
    int touchY;
    Pool <TouchEvent> touchEventPool;
    List <TouchEvent> touchEvents = new ArrayList <TouchEvent> ();
    List <TouchEvent> touchEventsBuffer = new ArrayList <TouchEvent> ();
    float scaleX;
    float scaleY;

    public SingleTouchHandler(View view, float scaleX, float scaleY) {
       PoolObjectFactory <TouchEvent> factory = new PoolObjectFactory <TouchEvent> () {
            @Override
            public TouchEvent createObject() {
                return new TouchEvent();
            }
        };
        touchEventPool = new Pool <TouchEvent> (factory, 100);
        view.setOnTouchListener(this );
        this.scaleX = scaleX;
        this.scaleY = scaleY;
    }

    public boolean onTouch(View v, MotionEvent event) {
        synchronized (this ) {
            TouchEvent touchEvent = touchEventPool.newObject();
            switch (event.getAction()) {
            case MotionEvent.ACTION_DOWN:
                touchEvent.type = TouchEvent.TOUCH_DOWN;
                isTouched = true ;
                break ;
            case MotionEvent.ACTION_MOVE:
                touchEvent.type = TouchEvent.TOUCH_DRAGGED;
                isTouched = true ;
                break ;
            case MotionEvent.ACTION_CANCEL:
            case MotionEvent.ACTION_UP:
                touchEvent.type = TouchEvent.TOUCH_UP;
                isTouched = false ;
                break ;
            }
            touchEvent.x = touchX = (int )(event.getX() * scaleX);
            touchEvent.y = touchY = (int )(event.getY() * scaleY);
            touchEventsBuffer.add(touchEvent);
            return true ;
        }
    }

    public boolean isTouchDown(int pointer) {
        synchronized (this ) {
            if (pointer == 0)
                return isTouched;
            else 
                return false ;
        }
    }
    public int getTouchX(int pointer) {
        synchronized (this ) {
            return touchX;
        }
    }
    public int getTouchY(int pointer) {
        synchronized (this ) {
            return touchY;
        }
    }

    public List <TouchEvent> getTouchEvents() {
        synchronized (this ) {
            int len = touchEvents.size();
            for (int i = 0; i < len; i++ )
                touchEventPool.free(touchEvents.get(i));
            touchEvents.clear();
            touchEvents.addAll(touchEventsBuffer);
            touchEventsBuffer.clear();
            return touchEvents;
        }
    }
}

package com.badlogic.androidgames.framework.impl;

import java.util.ArrayList;
import java.util.List;

import android.view.MotionEvent;
import android.view.View;

import com.badlogic.androidgames.framework.Input.TouchEvent;
import com.badlogic.androidgames.framework.Pool;
import com.badlogic.androidgames.framework.Pool.PoolObjectFactory;

@TargetApi(5) 
public class MultiTouchHandler implements TouchHandler {
    private static final int MAX_TOUCHPOINTS = 10;
    boolean [] isTouched = new boolean [MAX_TOUCHPOINTS];
    int [] touchX = new int [MAX_TOUCHPOINTS];
    int [] touchY = new int [MAX_TOUCHPOINTS];
    int [] id = new int [MAX_TOUCHPOINTS];
    Pool <TouchEvent> touchEventPool;
    List <TouchEvent> touchEvents = new ArrayList <TouchEvent> ();
    List <TouchEvent> touchEventsBuffer = new ArrayList <TouchEvent> ();
    float scaleX;
    float scaleY;

    public MultiTouchHandler(View view, float scaleX, float scaleY) {
        PoolObjectFactory <TouchEvent> factory = new PoolObjectFactory <TouchEvent> () {
            public TouchEvent createObject() {
                return new TouchEvent();
            }
        };
        touchEventPool = new Pool <TouchEvent> (factory, 100);
        view.setOnTouchListener(this );
        this.scaleX = scaleX;
        this.scaleY = scaleY;
    }
    public boolean onTouch(View v, MotionEvent event) {
        synchronized (this ) {
            int action = event.getAction() & MotionEvent.ACTION_MASK;
            int pointerIndex = (event.getAction() & MotionEvent.ACTION_POINTER_ID_MASK) > > MotionEvent.ACTION_POINTER_ID_SHIFT;
            int pointerCount = event.getPointerCount();
            TouchEvent touchEvent;
            for (int i = 0; i < MAX_TOUCHPOINTS; i++) {
                if (i >= pointerCount) {
                    isTouched[i] = false ;
                    id[i] = -1;
                    continue ;
                }
                int pointerId = event.getPointerId(i);
                if (event.getAction() != MotionEvent.ACTION_MOVE&& i != pointerIndex) {
                    // if it's an up/down/cancel/out event, mask the id to see if we should process it for this touch
                    // point
                    continue ;
                }
                switch (action) {
                case MotionEvent.ACTION_DOWN:
                case MotionEvent.ACTION_POINTER_DOWN:
                    touchEvent = touchEventPool.newObject();
                    touchEvent.type = TouchEvent.TOUCH_DOWN;
                    touchEvent.pointer = pointerId;
                    touchEvent.x = touchX[i] = (int ) (event.getX(i) * scaleX);
                    touchEvent.y = touchY[i] = (int ) (event.getY(i) * scaleY);
                    isTouched[i] = true ;
                    id[i] = pointerId;
                    touchEventsBuffer.add(touchEvent);
                    break ;

                case MotionEvent.ACTION_UP:
                case MotionEvent.ACTION_POINTER_UP:
                case MotionEvent.ACTION_CANCEL:
                    touchEvent = touchEventPool.newObject();
                    touchEvent.type = TouchEvent.TOUCH_UP;
                    touchEvent.pointer = pointerId;
                    touchEvent.x = touchX[i] = (int ) (event.getX(i) * scaleX);
                    touchEvent.y = touchY[i] = (int ) (event.getY(i) * scaleY);
                    isTouched[i] = false ;
                    id[i] = -1;
                    touchEventsBuffer.add(touchEvent);
                    break ;

                case MotionEvent.ACTION_MOVE:
                    touchEvent = touchEventPool.newObject();
                    touchEvent.type = TouchEvent.TOUCH_DRAGGED;
                    touchEvent.pointer = pointerId;
                    touchEvent.x = touchX[i] = (int ) (event.getX(i) * scaleX);
                    touchEvent.y = touchY[i] = (int ) (event.getY(i) * scaleY);
                    isTouched[i] = true ;
                    id[i] = pointerId;
                    touchEventsBuffer.add(touchEvent);
                    break ;
                }
            }
            return true ;
        }
    }
    public boolean isTouchDown(int pointer) {
        synchronized (this ) {
            int index = getIndex(pointer);
            if (index < 0 || index >=MAX_TOUCHPOINTS)
                return false ;
            else 
                return isTouched[index];
        }
    }
    public int getTouchX(int pointer) {
        synchronized (this ) {
            int index = getIndex(pointer);
            if (index < 0 || index >=MAX_TOUCHPOINTS)
                return 0;
            else 
                return touchX[index];
        }
    }
    public int getTouchY(int pointer) {
        synchronized (this ) {
            int index = getIndex(pointer);
            if (index < 0 || index >=MAX_TOUCHPOINTS)
                return 0;
            else 
                return touchY[index];
        }
    }
    public List <TouchEvent> getTouchEvents() {
        synchronized (this ) {
            int len = touchEvents.size();
            for (int i = 0; i < len; i++)
                touchEventPool.free(touchEvents.get(i));
            touchEvents.clear();
            touchEvents.addAll(touchEventsBuffer);
            touchEventsBuffer.clear();
            return touchEvents;
        }
    }
    // returns the index for a given pointerId or −1 if no index.
    private int getIndex(int pointerId) {
        for (int i = 0; i < MAX_TOUCHPOINTS; i++) {
            if (id[i] == pointerId) {
                return i;
            }
        }
        return -1;
    }
}

AndroidInput: The Great Coordinator

The Input implementation of our game framework ties together all the handlers we have developed. Any method calls are delegated to the corresponding handler. The only interesting part of this implementation is choosing which TouchHandler implementation to use, based on the Android version the device is running. Listing 5-12 shows an implementation called AndroidInput, with commentary.

Listing 5-12. AndroidInput.java; Handling the Handlers with Style

package com.badlogic.androidgames.framework.impl;

import java.util.List;

import android.content.Context;
import android.os.Build.VERSION;
import android.view.View;

import com.badlogic.androidgames.framework.Input;

public class AndroidInput implements Input {
    AccelerometerHandler accelHandler;
    KeyboardHandler keyHandler;
    TouchHandler touchHandler;

We start by letting the class implement the Input interface defined in Chapter 3. This leads us to three members: an AccelerometerHandler, a KeyboardHandler, and a TouchHandler.

    public AndroidInput(Context context, View view, float scaleX, float scaleY) {
        accelHandler = new AccelerometerHandler(context);
        keyHandler = new KeyboardHandler(view);
        if (Integer.parseInt(VERSION.SDK) < 5)
            touchHandler = new SingleTouchHandler(view, scaleX, scaleY);
        else 
            touchHandler = new MultiTouchHandler(view, scaleX, scaleY);
    }

These members are initialized in the constructor, which takes a Context, a View, and the scaleX and scaleY parameters, which we can ignore again. The AccelerometerHandler is instantiated via the Context parameter, as the KeyboardHandler needs the View that is passed in.

To decide which TouchHandler to use, we simply check the Android version that the application uses to run. This can be done using the VERSION.SDK string, which is a constant provided by the Android API. It is unclear why this is a string, since it directly encodes the SDK version numbers we use in our manifest file. Therefore, we need to make it into an integer in order to do some comparisons. The first Android version to support the multitouch API was version 2.0, which corresponds to SDK version 5. If the current device runs a lower Android version, we instantiate the SingleTouchHandler; otherwise, we use the MultiTouchHandler. At an API level, this is all the fragmentation we need to care about. When we start rendering OpenGL, we’ll hit a few more fragmentation issues, but there is no need to worry—they are easily resolved, just like the touch API problems.

    public boolean isKeyPressed(int keyCode) {
        return keyHandler.isKeyPressed(keyCode);
    }
    public boolean isTouchDown(int pointer) {
        return touchHandler.isTouchDown(pointer);
    }
    public int getTouchX(int pointer) {
        return touchHandler.getTouchX(pointer);
    }
    public int getTouchY(int pointer) {
        return touchHandler.getTouchY(pointer);
    }
    public float getAccelX() {
        return accelHandler.getAccelX();
    }
    public float getAccelY() {
        return accelHandler.getAccelY();
    }
    public float getAccelZ() {
        return accelHandler.getAccelZ();
    }
    public List <TouchEvent> getTouchEvents() {
        return touchHandler.getTouchEvents();
    }
    public List <KeyEvent> getKeyEvents() {
        return keyHandler.getKeyEvents();
    }
}

The rest of this class is self-explanatory. Each method call is delegated to the appropriate handler, which does the actual work. With this, we have finished the input API of our game framework. Next, we’ll discuss graphics.

Handling Different Screen Sizes and Resolutions

Android has supported different screen resolutions since version 1.6. It can handle resolutions ranging from 240×320 pixels to a full HDTV resolution of 1920×1080. In Chapter 4, we discussed the effect of different screen resolutions and physical screen sizes. For instance, drawing with absolute coordinates and sizes given in pixels will produce unexpected results. Figure 5-1 shows what happens when we render a 100×100-pixel rectangle with the upper-left corner at (219,379) on 480×800 and 320×480 screens.

This difference is problematic for two reasons. First, we can’t draw our game and assume a fixed resolution. The second reason is more subtle: in Figure 5-1, we assumed that both screens have the same density (that is, each pixel has the same physical size on both devices), but this is rarely the case in reality.

AndroidPixmap: Pixels for the People

According to the design of our Pixmap interface from Chapter 3, there’s not much to implement. Listing 5-13 presents the code.

Listing 5-13. AndroidPixmap.java, a Pixmap Implementation Wrapping a Bitmap

package com.badlogic.androidgames.framework.impl;

import android.graphics.Bitmap;

import com.badlogic.androidgames.framework.Graphics.PixmapFormat;
import com.badlogic.androidgames.framework.Pixmap;

public class AndroidPixmapimplements Pixmap {
    Bitmap bitmap;
    PixmapFormat format;

    public AndroidPixmap(Bitmap bitmap, PixmapFormat format) {
        this.bitmap = bitmap;
        this.format = format;
    }
    public int getWidth() {
        return bitmap.getWidth();
    }
    public int getHeight() {
        return bitmap.getHeight();
    }
    public PixmapFormat getFormat() {
        return format;
    }
    public void dispose() {
        bitmap.recycle();
    }
}

All we need to do is store the Bitmap instance that we wrap, along with its format, which is stored as a PixmapFormat enumeration value, as defined in Chapter 3. Additionally, we implement the required methods of the Pixmap interface so that we can query the width and height of the Pixmap, as well as its format, and ensure that the pixels can be dumped from RAM. Note that the Bitmap member is package private, so we can access it in AndroidGraphics, which we’ll implement now.

AndroidGraphics: Serving Our Drawing Needs

The Graphics interface we designed in Chapter 3 is also lean and mean. It will draw pixels, lines, rectangles, and Pixmaps to the framebuffer. As discussed, we’ll use a Bitmap as our framebuffer and direct all drawing calls to it via a Canvas. It is also responsible for creating Pixmap instances from asset files. Therefore, we’ll also need another AssetManager. Listing 5-14 shows the code for our implementation of the interface, AndroidGraphics, with commentary.

Listing 5-14. AndroidGraphics.java; Implementing the Graphics Interface

package com.badlogic.androidgames.framework.impl;

import java.io.IOException;
import java.io.InputStream;

import android.content.res.AssetManager;
import android.graphics.Bitmap;
import android.graphics.Bitmap.Config;
import android.graphics.BitmapFactory;
import android.graphics.BitmapFactory.Options;
import android.graphics.Canvas;
import android.graphics.Paint;
import android.graphics.Paint.Style;
import android.graphics.Rect;

import com.badlogic.androidgames.framework.Graphics;
import com.badlogic.androidgames.framework.Pixmap;

public class AndroidGraphics implements Graphics {
    AssetManager assets;
    Bitmap frameBuffer;
    Canvas canvas;
    Paint paint;
    Rect srcRect = new Rect();
    Rect dstRect = new Rect();

The class implements the Graphics interface. It contains an AssetManager member that we use to load Bitmap instances, a Bitmap member that represents our artificial framebuffer, a Canvas member that we use to draw to the artificial framebuffer, a Paint member we need for drawing, and two Rect members we need for implementing the AndroidGraphics.drawPixmap() methods. These last three members are there so we don’t have to create new instances of these classes on every draw call. That would create a number of problems for the garbage collector.

    public AndroidGraphics(AssetManager assets, Bitmap frameBuffer) {
        this.assets = assets;
        this.frameBuffer = frameBuffer;
        this.canvas = new Canvas(frameBuffer);
        this.paint = new Paint();
    }

In the constructor, we get an AssetManager and Bitmap that represent our artificial framebuffer from the outside. We store these in the respective members and create the Canvas instance that will draw the artificial framebuffer, as well as the Paint, which we use for some of the drawing methods.

    public Pixmap newPixmap(String fileName, PixmapFormat format) {
        Config config = null ;
        if (format == PixmapFormat.RGB565)
            config = Config.RGB_565;
        else if (format == PixmapFormat.ARGB4444)
            config = Config.ARGB_4444;
        else 
            config = Config.ARGB_8888;

        Options options = new Options();
        options.inPreferredConfig = config;

        InputStream in = null ;
        Bitmap bitmap = null ;
        try {
            in = assets.open(fileName);
            bitmap = BitmapFactory.decodeStream(in);
            if (bitmap ==null )
                throw new RuntimeException("Couldn't load bitmap from asset '"
                        + fileName + "'");
        }catch (IOException e) {
            throw new RuntimeException("Couldn't load bitmap from asset '"
                    + fileName + "'");
        }finally {
            if (in != null ) {
                try {
                    in.close();
                }catch (IOException e) {
                }
            }
        }
        if (bitmap.getConfig() == Config.RGB_565)
            format = PixmapFormat.RGB565;
        else if (bitmap.getConfig() == Config.ARGB_4444)
            format = PixmapFormat.ARGB4444;
        else 
            format = PixmapFormat.ARGB8888;

        return new AndroidPixmap(bitmap, format);
    }

The newPixmap() method tries to load a Bitmap from an asset file, using the specified PixmapFormat. We start by translating the PixmapFormat into one of the constants of the Android Config class used in Chapter 4. Next, we create a new Options instance and set our preferred color format. Then, we try to load the Bitmap from the asset via the BitmapFactory, and throw a RuntimeException if something goes wrong. Otherwise, we check what format the BitmapFactory used to load the Bitmap and translate it into a PixmapFormat enumeration value. Remember that the BitmapFactory might decide to ignore our desired color format, so we have to check to determine what it used to decode the image. Finally, we construct a new AndroidBitmap instance based on the Bitmap we loaded, as well as its PixmapFormat, and return it to the caller.

    public void clear(int color) {
        canvas.drawRGB((color & 0xff0000) >> 16, (color & 0xff00) >> 8,
                (color & 0xff));
    }

The clear() method extracts the red, green, and blue components of the specified 32-bit ARGB color parameter and calls the Canvas.drawRGB() method, which clears our artificial framebuffer with that color. This method ignores any alpha value of the specified color, so we don’t have to extract it.

    public void drawPixel(int x, int y, int color) {
        paint.setColor(color);
        canvas.drawPoint(x, y, paint);
    }

The drawPixel() method draws a pixel of our artificial framebuffer via the Canvas.drawPoint() method. First, we set the color of our Paint member variable and pass it to the drawing method in addition to the x and y coordinates of the pixel.

    public void drawLine(int x, int y, int x2, int y2, int color) {
        paint.setColor(color);
        canvas.drawLine(x, y, x2, y2, paint);
    }

The drawLine() method draws the given line of the artificial framebuffer, using the Paint member to specify the color when calling the Canvas.drawLine() method.

    public void drawRect(int x, int y, int width, int height, int color) {
        paint.setColor(color);
        paint.setStyle(Style.FILL);
        canvas.drawRect(x, y, x + width - 1, y + width - 1, paint);
    }

The drawRect() method sets the Paint member’s color and style attributes so that we can draw a filled, colored rectangle. In the actual Canvas.drawRect() call, we have to transform the x, y, width, and height parameters of the coordinates in the top-left and bottom-right corners of the rectangle. For the top-left corner, we simply use the x and y parameters. For the bottom-right corner, we add the width and height to x and y and subtract 1. For example, if we render a rectangle with an x and y of (10,10) and a width and height of 2 and 2 and we don’t subtract 1, the resulting rectangle on the screen will be 3×3 pixels in size.

    public void drawPixmap(Pixmap pixmap, int x, int y, int srcX, int srcY,
            int srcWidth, int srcHeight) {
        srcRect.left = srcX;
        srcRect.top = srcY;
        srcRect.right = srcX + srcWidth - 1;
        srcRect.bottom = srcY + srcHeight - 1;

        dstRect.left = x;
        dstRect.top = y;
        dstRect.right = x + srcWidth - 1;
        dstRect.bottom = y + srcHeight - 1;

        canvas.drawBitmap(((AndroidPixmap) pixmap).bitmap, srcRect, dstRect, null );
    }

The drawPixmap() method, which allows us to draw a portion of a Pixmap, sets up the source and destination of the Rect members that are used in the actual drawing call. As with drawing a rectangle, we have to translate the x and y coordinates together with the width and height to the top-left and bottom-right corners. Again, we have to subtract 1, or else we will overshoot by 1 pixel. Next, we perform the actual drawing via the Canvas.drawBitmap() method, which will automatically do the blending if the Pixmap we draw has a PixmapFormat.ARGB4444 or a PixmapFormat.ARGB8888 color depth. Note that we have to cast the Pixmap parameter to an AndroidPixmap in order to fetch the bitmap member for drawing with the Canvas. That’s a bit complicated, but we can be sure that the Pixmap instance that is passed in will be an AndroidPixmap.

    public void drawPixmap(Pixmap pixmap, int x, int y) {
        canvas.drawBitmap(((AndroidPixmap)pixmap).bitmap, x, y, null );
    }

The second drawPixmap() method draws the complete Pixmap to the artificial framebuffer at the given coordinates. Again, we must do some casting to get to the Bitmap member of the AndroidPixmap.

    public int getWidth() {
        return frameBuffer.getWidth();
    }
    public int getHeight() {
        return frameBuffer.getHeight();
    }
}

Finally, we have the methods getWidth() and getHeight(), which simply return the size of the artificial framebuffer stored by the AndroidGraphics class to which it renders internally.

AndroidFastRenderView is the last class we need in order to implement.

AndroidFastRenderView: Loop, Stretch, Loop, Stretch

The name of this class should give away what lies ahead. In Chapter 4, we discussed using a SurfaceView to perform continuous rendering in a separate thread that could also house our game’s main loop. We developed a very simple class called FastRenderView, which was derived from the SurfaceView class, we made sure we play nice with the activity life cycle, and we set up a thread in order to constantly render the SurfaceView via a Canvas. Here, we’ll reuse this FastRenderView class and augment it to do a few more things:

• It keeps a reference to a Game instance from which it can get the active Screen. We constantly call the Screen.update() and Screen.present() methods from within the FastRenderView thread.
• It keeps track of the delta time between frames that is passed to the active Screen.

It takes the artificial framebuffer to which the AndroidGraphics instance draws, and draws it to the SurfaceView, which is scaled if necessary.

Listing 5-15 shows the implementation of the AndroidFastRenderView class, with commentary where appropriate.

Listing 5-15. AndroidFastRenderView.java, a Threaded SurfaceView Executing Our Game Code

package com.badlogic.androidgames.framework.impl;

import android.graphics.Bitmap;
import android.graphics.Canvas;
import android.graphics.Rect;
import android.view.SurfaceHolder;
import android.view.SurfaceView;

public class AndroidFastRenderViewextends SurfaceView implements Runnable {
    AndroidGame game;
    Bitmap framebuffer;
    Thread renderThread = null ;
    SurfaceHolder holder;
    volatile boolean running = false ;

This should look familiar. We just need to add two more members—an AndroidGame instance and a Bitmap instance that represent our artificial framebuffer. The other members are the same as in our FastRenderView from Chapter 3.

    public AndroidFastRenderView(AndroidGame game, Bitmap framebuffer) {
        super (game);
        this.game = game;
        this.framebuffer = framebuffer;
        this.holder = getHolder();
    }

In the constructor, we simply call the base class’s constructor with the AndroidGame parameter (which is an Activity; this will be discussed in the following sections) and store the parameters in the respective members. Once again, we get a SurfaceHolder, as in previous sections.

    public void resume() {
        running = true ;
        renderThread = new Thread(this );
        renderThread.start();
    }

The resume() method is an exact copy of the FastRenderView.resume() method, so we won’t discuss it again. In short, the method makes sure that our thread interacts nicely with the activity life cycle.

    public void run() {
        Rect dstRect = new Rect();
        long startTime = System.nanoTime();
        while (running) {
            if (!holder.getSurface().isValid())
                continue ;

            float deltaTime = (System.nanoTime()-startTime) / 1000000000.0f;
            startTime = System.nanoTime();

            game.getCurrentScreen().update(deltaTime);
            game.getCurrentScreen().present(deltaTime);

            Canvas canvas = holder.lockCanvas();
            canvas.getClipBounds(dstRect);
            canvas.drawBitmap(framebuffer, null , dstRect, null );
            holder.unlockCanvasAndPost(canvas);
        }
    }

The run() method has a few more features. The first addition is its ability to track delta time between each frame. For this, we use System.nanoTime(), which returns the current time in nanoseconds as a long.

In each loop iteration, we start by taking the difference between the last loop iteration’s start time and the current time. To make it easier to work with that delta, we convert it into seconds. Next, we save the current timestamp, which we’ll use in the next loop iteration, to calculate the next delta time. With the delta time at hand, we call the current Screen instance’s update() and present() methods, which will update the game logic and render things to the artificial framebuffer. Finally, we get a hold of the Canvas for the SurfaceView and draw the artificial framebuffer. The scaling is performed automatically in case the destination rectangle we pass to the Canvas.drawBitmap() method is smaller or bigger than the framebuffer.

Note that we’ve used a shortcut here to get a destination rectangle that stretches over the whole SurfaceView via the Canvas.getClipBounds() method. It will set the top and left members of dstRect to 0 and 0, respectively, and the bottom and right members to the actual screen dimensions (480×800 in portrait mode on a Nexus One). The rest of the method is exactly the same as what we had in our FastRenderView test in the last chapter. The method simply makes sure that the thread stops when the activity is paused or destroyed.

    public void pause() {
        running = false ;
        while (true ) {
            try {
                renderThread.join();
                return ;
            }catch (InterruptedException e) {
                // retry
            }
        }
    }
}

The last method of this class, pause(), is also the same as in the FastRenderView.pause() method—it simply terminates the rendering/main loop thread and waits for it to die completely before returning.

We are nearly done with our framework. The last piece of the puzzle is the implementation of the Game interface.