Why Ogg Vorbis?
    

• MP3 technology is encumbered by patents and I don't want to have to worry about paying royalties or being sued sometime in the future.
• Vorbis is variable bitrate by default, and in listening tests the quality is at least as good as MP3.
• Vorbis also supports gapless encoding, which is a requirement for seamless looping (possible with MP3, but hard).
• There's a very efficient ARM-optimized New-BSD-licensed (free to use) decoder called Tremor (there is also Tremolo, which is even faster).

    Compiling an open-source C++ project for Android NDK
    
The first step is to download the source code and save it to a directory on your hard drive. Then we'll open up a Cygwin prompt by running C:\cygwin\Cygwin.bat and navigate to that folder. Then execute the following command:

./configure --host=arm-android-linux --target=arm-android-linux

This creates a config.h file that tells the open-source project a bit about the destination architecture and environment.

Note: I don't know if those parameters above are exactly right. If you do know the optimal parameters, answer my question on Stack Overflow.


Now, you can either do things the hard way and use the Makefile to compile an Android library (.so) and link that into your project. Or just drag-and-drop the required files into Visual Studio:


Note: Before embedding an open-source library into Visual Studio instead of linking a library or loading a .DLL, check the license terms of the project to make sure this is ok.


    Enable optimizations and fix compile problems

First off, I had some compile errors which I fixed by adding the following to os.h:

#define LITTLE_ENDIAN 1 #define BYTE_ORDER LITTLE_ENDIAN

Then I wanted to enable the ARM-specific assembler optimizations (which sped up the decoding by about 100%), so I added the following to asm_arm.h:

#define _ARM_ASSEM_


    Convert Ogg/Vorbis to PCM
    
The Tremor library is designed to work with FILE* input, but we're able to create our own callbacks to duplicate this behaviour while reading a memory buffer:

static unsigned int suiCurrPos = 0; static unsigned int suiSize = 0; static size_t read_func(void* ptr, size_t size, size_t nmemb, void* datasource) { unsigned int uiBytes = Min(suiSize - suiCurrPos, (unsigned int)nmemb * (unsigned int)size); memcpy(ptr, (unsigned char*)datasource + suiCurrPos, uiBytes); suiCurrPos += uiBytes; return uiBytes; } static int seek_func(void* datasource, ogg_int64_t offset, int whence) { if (whence == SEEK_SET) suiCurrPos = (unsigned int)offset; else if (whence == SEEK_CUR) suiCurrPos = suiCurrPos + (unsigned int)offset; else if (whence == SEEK_END) suiCurrPos = suiSize; return 0; } static int close_func(void* datasource) { return 0; } static long tell_func(void* datasource) { return (long)suiCurrPos; }

Now we can send it an Ogg/Vorbis buffer already resident in memory:

void* ConvertOggToPCM(unsigned int uiOggSize, void* pvOggBuffer) { // Register callbacks OggVorbis_File vf; ov_callbacks callbacks; callbacks.read_func = &read_func; callbacks.seek_func = &seek_func; callbacks.close_func = &close_func; callbacks.tell_func = &tell_func; // Init Tremor suiCurrPos = 0; suiSize = uiOggSize; int iRet = ov_open_callbacks(pvOggBuffer, &vf, NULL, 0, callbacks); // Get sample info vorbis_info* vi = ov_info(&vf, -1); unsigned int uiPCMSamples = (unsigned int)ov_pcm_total(&vf, -1); void* pvPCMBuffer = malloc(uiPCMSamples * vi->channels * sizeof(short)); // Decode! int current_section = 0; long iRead = 0; unsigned int uiCurrPos = 0; do { iRead = ov_read(&vf, (char*)pvPCMBuffer + uiCurrPos, 4096, ¤t_section); uiCurrPos += (unsigned int)iRead; } while (iRead != 0); // Cleanup ov_clear(&vf); return pvPCMBuffer; }

    Saving to Internal Storage

The easiest place on Android to store small files tracking persistent data from your game is probably in the internal storage. You don't have to worry about SD cards being mounted or not, or needing any extra permissions in your manifest. The files can be created in a location un-accessible to other programs and the user, they will also be deleted automatically when your program is un-installed. Some things you might want to store: High Scores, Character Progression, Unlockables, etc...

import java.io.FileOutputStream; byte[] saveData = JNIGetSaveData(); int saveDataSize = JNIGetSaveDataSize(); try { String FILENAME = "saved_data"; FileOutputStream outputStream = openFileOutput(FILENAME, Context.MODE_PRIVATE); outputStream.write(saveData, 0, saveDataSize); outputStream.close(); } catch (final Exception ex) { Log.e("JAVA_DEBUGGING", "Exception while creating save file!"); ex.printStackTrace(); }

Here is the code that you can use to return a Java array from JNI:

jbyteArray Java_com_brokenteapot_firstgame_FirstGame_JNIGetSaveData(JNIEnv* env, void* reserved) { unsigned int uiSize = sizeof(unsigned int); unsigned int uiData = 0xFFFFFFFF; jbyteArray array = env->NewByteArray(uiSize); env->SetByteArrayRegion(array, 0, uiSize, (jbyte*)&uiData); return array; }

    Loading from internal storage
    
Loading is a bit trickier because you have to get the file size separately from the input stream. getFilesDir() returns the directory that contains the files created with openFileOutput().

import java.io.File; import java.io.FileInputStream; int size = 0; byte[] savedData = null; try { String FILENAME = "saved_data"; File file = new File(getFilesDir(), FILENAME); if (file.exists()) size = (int)file.length(); if (size != 0) { FileInputStream inputStream = openFileInput(FILENAME); savedState = new byte[size]; inputStream.read(savedState, 0, size); inputStream.close(); } } catch (final Exception ex) { Log.e("JAVA_DEBUGGING", "Exception while reading in saved data"); ex.printStackTrace(); }

When you need to send the byte array to JNI you can do the following:

void Java_com_brokenteapot_firstgame_FirstGame_JNILoadSaveData(JNIEnv* env, void* reserved, jbyteArray savedData, jlong savedDataSize) { // Get the byte* pointer from the Java array jboolean isCopy = JNI_TRUE; jbyte* savedDataElements = env->GetByteArrayElements(savedData, &isCopy); // Read the data unsigned int uiData = *(unsigned int*)savedDataElements; // Release the byte* pointer env->ReleaseByteArrayElements(savedData, savedDataElements, 0); }

    Verify your data
   
As always when saving/loading data from a physical storage medium, it's a good idea to verify that the data has not become corrupted (or been modified). You can use the code below to generate a CRC32 hash of your data and then append it to the end of your buffer.

/* Copyright (C) 1986 Gary S. Brown. You may use this program, or code or tables extracted from it, as desired without restriction.*/ static unsigned long crc_32_tab[] = { /* CRC polynomial 0xedb88320 */ 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d }; #define UPDC32(octet, crc) (crc_32_tab[((crc) ^ (octet)) & 0xff] ^ ((crc) >> 8)) unsigned long crc32buf(char* buf, size_t len) { unsigned long oldcrc32 = 0xFFFFFFFF; for ( ; len != 0; --len, ++buf) oldcrc32 = UPDC32(*buf, oldcrc32); return ~oldcrc32; }

Next time I will show you Ogg Vorbis audio decoding with the Android NDK.

    Playing a sample with an AudioTrack (Final version)

With the simple implementation of a static AudioTrack I showed you last time, as soon as the audioTrack variable goes out of scope it has the chance of being garbage collected. There is also no obvious place to insert this code and have it interface nicely with JNI. So what I did was put all my static AudioTrack processing in its own thread (streaming audio will get its own thread as well).

One very important thing to realize about an AudioTrack is that getPlayState() will always return PLAYSTATE_PLAYING unless you manually stop the track, even if the track is finished. To get around this rather amateurish design decision you have to compare the getPlaybackHeadPosition to a stored value for the number of samples you wrote to the AudioTrack to know when the tracks are finished (so that you can release their pointers and let them be garbage collected).

import java.util.LinkedList; import java.util.Queue; Thread mSampleThread; Runnable mSamples = new Runnable() { public void run() { Thread.currentThread().setPriority(Thread.MIN_PRIORITY); Queue<AudioTrack> queueTracks = new LinkedList<AudioTrack>(); Queue<Integer> queueTrackSamples = new LinkedList<Integer>(); while (!mStopAudioThreads) { // Delete any finished samples if (queueTracks.size() > 0) { int currentSamples = queueTracks.peek().getPlaybackHeadPosition(); int totalSamples = queueTrackSamples.peek(); if (currentSamples == totalSamples) { queueTracks.remove(); queueTrackSamples.remove(); } } // Check for new static samples to play int size = JNIAudioGetSampleToPlaySize(); if (size != 0) { short[] location = JNIAudioGetSampleToPlayLocation(); int channels = JNIAudioGetSampleToPlayChannels(); int samplesPerSecond = JNIAudioGetSampleToPlaySamplesPerSecond(); // Create a new AudioTrack for this static sample AudioTrack audioTrack; if (channels == 2) audioTrack = new AudioTrack(AudioManager.STREAM_MUSIC, samplesPerSecond, AudioFormat.CHANNEL_CONFIGURATION_STEREO, AudioFormat.ENCODING_PCM_16BIT, size, AudioTrack.MODE_STATIC); else audioTrack = new AudioTrack(AudioManager.STREAM_MUSIC, samplesPerSecond, AudioFormat.CHANNEL_CONFIGURATION_MONO , AudioFormat.ENCODING_PCM_16BIT, size, AudioTrack.MODE_STATIC); // Write the PCM data int sizeInShorts = size / 2; audioTrack.write(location, 0, sizeInShorts); // Play the track (and store the sample count for later) audioTrack.play(); queueTracks.add(audioTrack); queueTrackSamples.add(sizeInShorts / channels); } } } };

Here is the JNI code I use to create a new Java array and return it:

jshortArray Java_com_brokenteapot_firstgame_FirstGame_JNIAudioGetSampleToPlayLocation(JNIEnv* env, void* reserved) { jshortArray array = env->NewShortArray(spSampleToPlay->uiDataSize / 2); env->SetShortArrayRegion(array, 0, spSampleToPlay->uiDataSize / 2, (jshort*)spSampleToPlayData); return array; }


    Streaming into an AudioTrack
   
When streaming audio into an AudioTrack we follow the opposite sequence of calls from a static AudioTrack; we call play() and then write() into it. The way I have it set up below, C++ always returns a buffer every time the AudioTrack requires more data, but if no music is playing it writes silence into that buffer. This way I don't have to deal with pausing/unpausing the AudioTrack which was causing me a whole slew of problems for me.

My choice of 4x the size of the minimum buffer size for the streaming buffer was purely arbitrary, ~50K bytes is a good buffer size from my experiences with audio on other platforms (the minimum size on my test phone was 12288 bytes).
   
Runnable mStreams = new Runnable() { public void run() { // Create a streaming AudioTrack for music playback int minBufferSize = AudioTrack.getMinBufferSize(44100, AudioFormat.CHANNEL_CONFIGURATION_STEREO, AudioFormat.ENCODING_PCM_16BIT); int bufferSize = 4 * minBufferSize; short[] streamBuffer = new short[bufferSize / 2]; mMusicTrack = new AudioTrack(AudioManager.STREAM_MUSIC, 44100, AudioFormat.CHANNEL_CONFIGURATION_STEREO, AudioFormat.ENCODING_PCM_16BIT, bufferSize, AudioTrack.MODE_STREAM); mMusicTrack.play(); while (!mStopAudioThreads) { // Fill buffer with PCM data from C++ JNIAudioFillStreamBuffer(streamBuffer, bufferSize); // Stream PCM data into the music AudioTrack mMusicTrack.write(streamBuffer, 0, bufferSize / 2); } mMusicTrack.flush(); mMusicTrack.stop(); } };

Here is the JNI code I use to copy into the Java short array:

void Java_com_brokenteapot_firstgame_FirstGame_JNIAudioFillStreamBuffer(JNIEnv* env, void* reserved, jshortArray location, jint size) { // Get the short* pointer from the Java array jboolean isCopy = JNI_TRUE; jshort* dst = env->GetShortArrayElements(location, &isCopy); gAudioManager.FillStreamBuffer(dst, size); // Release the short* pointer env->ReleaseShortArrayElements(location, dst, 0); }


    Starting and stopping the threads
   
At the moment I'm calling these in onResume() and onPause().
   
void RunAudioThreads() { mStopAudioThreads = false; mSampleThread = new Thread(mSamples); mSampleThread.start(); mStreamThread = new Thread(mStreams); mStreamThread.start(); } void StopAudioThreads() { mStopAudioThreads = true; try { mSampleThread.join(); mStreamThread.join(); } catch(final Exception ex) { ex.printStackTrace(); } }



Next time I will show you how to store files in Android internal storage.

Unfortunately in Android 2.2, OpenSL has not yet been implemented for native audio playback in C++ so I will be using the Java audio functions for now.


Loading a RIFF format PCM .wav

If you are packing your audio data yourself like I am, the first step is to load up a .wav file.

struct RIFFHeader { char RIFF[4]; unsigned int fileSize; char WAVE[4]; char fmt[4]; unsigned int chunkSize; unsigned short audioFormat; unsigned short numOfChan; unsigned int samplesPerSec; unsigned int bytesPerSec; unsigned short blockAlign; unsigned short bitsPerSample; }; struct ChunkHeader { char subchunkID[4]; unsigned int subchunkSize; }; // Read in .wav RIFF header RIFFHeader header; fread(&header, sizeof(RIFFHeader), 1, pFileIn); printf("Channels: %u BitsPerSample: %u SamplesPerSec: %u\n", header.numOfChan, header.bitsPerSample, header.samplesPerSec); // Find the 'data' chunk unsigned int uiSizeSrcPCM = 0; while (true) { ChunkHeader chunkHeader; fread(&chunkHeader, sizeof(chunkHeader), 1, pFileIn); if (chunkHeader.subchunkID[0] == 'd' && chunkHeader.subchunkID[1] == 'a' && chunkHeader.subchunkID[2] == 't' && chunkHeader.subchunkID[3] == 'a') { uiSizeSrcPCM = chunkHeader.subchunkSize; break; } fseek(pFileIn, chunkHeader.subchunkSize, SEEK_CUR); } // Read in the PCM data void* pvDataPCM = malloc(uiSizeSrcPCM); fread(pvDataPCM, uiSizeSrcPCM, 1, pFileIn);

This isn't the safest code and I don't think it covers all cases (a 'list' chunk can sometimes be after the data chunk), but it worked for me with .wav saved by both Windows Sound Recorder and Audacity 1.3.13. If you find some .wav that are giving you problems, loading and then exporting them back to .wav with something like Audacity ought to do the trick.

The fields that are important to us are the number of channels (numOfChan), the sample size (bitsPerSample), and the number of bytes per second (samplesPerSec). The PCM data we loaded into pvDataPCM can be sent directly to the AudioTrack below as a short[].


JNI Interface

I've decided to embed my audio samples into my already existing packed data file, and load the them the same way I load my OpenGL textures (in C++). This is the best way to go I feel, in preparation for 2.3 when we'll be able to play audio directly from C++ with OpenSL. So for now we need a way to get the information out of the C++ code and into the Java code.

On the Java side:

private static native short[] JNIAudioGetSampleToPlayLocation(); private static native int JNIAudioGetSampleToPlaySize(); private static native int JNIAudioGetSampleToPlayChannels(); private static native int JNIAudioGetSampleToPlaySamplesPerSecond();

And on the C++ side:

jshortArray Java_com_brokenteapot_firstgame_FirstGame_JNIAudioGetSampleToPlayLocation(JNIEnv* env, void* reserved) { return (jshortArray)pvSampleBuffer; } jint Java_com_brokenteapot_firstgame_FirstGame_JNIAudioGetSampleToPlaySize(JNIEnv* env, void* reserved) { return uiDataSize; } jint Java_com_brokenteapot_firstgame_FirstGame_JNIAudioGetSampleToPlayChannels(JNIEnv* env, void* reserved) { return uiChannels; } jint Java_com_brokenteapot_firstgame_FirstGame_JNIAudioGetSampleToPlaySamplesPerSecond(JNIEnv* env, void* reserved) { return uiSamplesPerSecond; }



Playing the sample with an AudioTrack

import android.media.AudioFormat; import android.media.AudioManager; import android.media.AudioTrack; // Get the sample information from C++ short[] location = JNIAudioGetSampleToPlayLocation(); int size = JNIAudioGetSampleToPlaySize(); int channels = JNIAudioGetSampleToPlayChannels(); int samplesPerSecond = JNIAudioGetSampleToPlaySamplesPerSecond(); // Create an Audio Track AudioTrack audioTrack; if (channels == 2) audioTrack = new AudioTrack(AudioManager.STREAM_MUSIC, samplesPerSecond, AudioFormat.CHANNEL_CONFIGURATION_STEREO, AudioFormat.ENCODING_PCM_16BIT, size, AudioTrack.MODE_STATIC); else audioTrack = new AudioTrack(AudioManager.STREAM_MUSIC, samplesPerSecond, AudioFormat.CHANNEL_CONFIGURATION_MONO , AudioFormat.ENCODING_PCM_16BIT, size, AudioTrack.MODE_STATIC); // Write the PCM data int sizeInShorts = size / 2; audioTrack.write(location, 0, sizeInShorts); // Play the sound audioTrack.play();



Next time I'll show you how to stream music into an AudioTrack as well as create two seperate threads, one for static samples and one for streaming samples.

    Understanding licenses

Although all of the art on the following sites is 'free', some of the licenses attached to the art mandate certain restrictions. For example some of the authors have chosen licenses that force your entire project to use the same license as the single piece of artwork, others oblige you to open-source your source-code and include it with your game. Of course, you can try to contact the author to have these restrictions waived on a case-by-case basis, or perhaps offer to purchase a license to the art.

One very acceptable condition that some licenses attach is an attribution clause, where you have to acknowledge the creator of the art (most likely in your credits). Another acceptable (but very annoying) condition is that you need to include the original source of the art you are using. I'm honestly not sure how that would work with an Android package though, I don't know if an uncompressed .png included in the package would be sufficient?

The good licenses (truly free, or attribution):

• Creative Commons Attribution 3.0 (CC BY 3.0)
• Zero Copyright (CC0)
• Public Domain (Copyright-Only Dedication)

The annoying licenses (not sure exactly how to handle them):

• GNU LGPL 3 (LGPL 3.0)
• GNU LGPL 2 (LGPL 2.1)

The bad licenses (author forces his personal philosophy on your entire project):

• Creative Commons Attribution-Share Alike 3.0 (CC BY-SA 3.0)
• GNU GPL 3 (GPL 3.0)
• GNU GPL 2 (GPL 2.0)

    The Sites

Open Game Art
    
Directly targeted towards game art, with a great search interface where you can specify exactly the licenses you want. Seems mostly geared towards RPG sprite artwork however, and very few of the sprites are animated. If you're looking to make a Dragon's Quest style RPG with static fight scenes this place is heaven on earth. For other types of games, not too useful.

Free Art Search

A pretty good image search which seems to have a bit more selection than Open Game Art, with the trade-off that most of the licenses are 'unknown' and you would have to track down the original author to verify that you can use it. And again, almost none of the images are animated.

Reiner`s Tilesets

Completely free to use 2D and 3D artwork done in an Ultima Online art style.

Open Clip Art

Although not at all game focused, this site is actually a lot more useful to me than the above ones. Obviously being clip-art, nothing is animated, but every single image is released under the CC0 Public Domain Dedication, so anything I find I'm guaranteed to be able to use. Also the art styles are more similar to what I envision for my project than the pixel art from the two previous sites. The search works beautifully and there is a huge selection to chose from.

Icon Finder

A great search engine for small images and GUI elements. It is very easy to filter the search to exclude non-commercial-allowed images.

   
    The Collections
   
GfxLib-Fuzed

A great collection of platformer game graphics, including tilesets, sprites and backgrounds. Professionally done with full animations on the sprites. Artwork is royalty free and can be used commercially.

SpriteLib

A big collection of 80s-style arcade sprites. Contains lots of airplane and tank graphics, as well as some more generic platformer sprites. A welcome change from all the RPG-heavy graphics I've found elsewhere. Free to use for any use.

Circle Textures

Beautiful terrain tiles, could conceivably be used for the terrain of an RTS game. Free to use by anyone, with attribution.

Airplane Sprite Pack and Airplane and Tank Sprite Pack

Fucking cool looking planes and tanks. Free to use with attribution and notification of the author. Makes me wish I was working on an airplane game, these sprites are awesome.


    Conclusion
   
Based on a quick look around on the above sites I'd say that they're not useful for much more than placeholder art and perhaps GUI elements in your final game. You'd be better off creating a game based on the art you find rather than trying to find art for an existing game concept. The quantity simply isn't there for you to be able to find something in particular that you're looking for. Looks like I'll be looking to hire an artist some time in the future.


Next time I will show you how to play .wav files with AudioTrack.

As I discussed before in my blog post about PVRTC texture encoding and performance, every Android OpenGL ES 2.0 phone supports at least two texture formats: ETC1 and one of the three proprietary formats (PVRTC, ATITC and S3TC). I just got myself a cheap second-hand Nexus One (with an Adreno 200 graphics chip), so I wanted to test out the ATI-specific texture format and see what the trade-offs are vs. ETC1 texture performance.


    Get the Adreno SDK
    
Get adreno-sdk-2-2-00.zip from the Qualcomm developer website. Free registration is required (WARNING: They send you your own password in plaintext). Once installed it will be placed in C:\Program Files (x86)\Qualcomm\AdrenoSDK\.


    Encoding ATC textures

Unlike with PVRTC, the SDK does not contain a stand-alone executable, it contains a library that has to be directly linked into your packing program. The documentation explaining in detail how to do that is located in AdrenoSDK\Tools\Texture Converter\docs. After including the appropriate header file (TextureConverter.h) and linking with the library (TextureConverter.lib), your code will look something like the following (this is directly based on AdrenoSDK\Tools\Texture Converter\samples\Convert.c).

The first step is to initialize the source image (in my case a .tga file):

// Read in .tga header TGA_HEADER header; fread(&header, sizeof(TGA_HEADER), 1, pFileIn); TQonvertImage qualcommTextureInput; qualcommTextureInput.pFormatFlags = (TFormatFlags*)malloc(sizeof(TFormatFlags)); memset(qualcommTextureInput.pFormatFlags, 0, sizeof(TFormatFlags)); qualcommTextureInput.nWidth = header.width; qualcommTextureInput.nHeight = header.height; qualcommTextureInput.nFormat = header.bpp == 24 ? Q_FORMAT_RGB_888 : Q_FORMAT_RGBA_8888; qualcommTextureInput.nDataSize = header.width * header.height * header.bpp / 8; qualcommTextureInput.pFormatFlags->nMaskRed = 0xFF0000; qualcommTextureInput.pFormatFlags->nMaskGreen = 0x00FF00; qualcommTextureInput.pFormatFlags->nMaskBlue = 0x0000FF; qualcommTextureInput.pFormatFlags->nFlipY = 1; qualcommTextureInput.pData = (unsigned char*)malloc(qualcommTextureInput.nDataSize); fread(qualcommTextureInput.pData, uiSizeSrcTGA, 1, pFileIn);

Then we setup the destination image (either ATITC_RGB or ATITC_RGBA):

TQonvertImage qualcommTextureOutput; qualcommTextureOutput.pFormatFlags = (TFormatFlags*)malloc(sizeof(TFormatFlags)); memset(qualcommTextureOutput.pFormatFlags, 0, sizeof(TFormatFlags)); qualcommTextureOutput.nWidth = qualcommTextureInput.nWidth; qualcommTextureOutput.nHeight = qualcommTextureInput.nHeight; qualcommTextureOutput.nFormat = uiType == TEXTURE_FORMAT_ATCRGB ? Q_FORMAT_ATITC_RGB : Q_FORMAT_ATITC_RGBA; qualcommTextureOutput.nDataSize = 0; qualcommTextureOutput.pData = NULL; // Get size of destination texture by passing in NULL data and zero size Qonvert(&qualcommTextureInput, &qualcommTextureOutput); qualcommTextureOutput.pData = (unsigned char*)malloc(qualcommTextureOutput.nDataSize);

Finally we do the actual conversion from .tga to ATC:

// Convert texture and write to file Qonvert(&qualcommTextureInput, &qualcommTextureOutput); fwrite(qualcommTextureOutput.pData, 1, qualcommTextureOutput.nDataSize, _pFileData); // Cleanup free(qualcommTextureInput.pData); free(qualcommTextureInput.pFormatFlags); free(qualcommTextureOutput.pData); free(qualcommTextureOutput.pFormatFlags);


    Loading ATC textures

Nothing special needs to be done to load ATC textures, just make a regular call to glCompressedTexImage2D with the right constant (substitute GL_ATC_RGBA_EXPLICIT_ALPHA_AMD for ATC alpha textures).

glCompressedTexImage2D(GL_TEXTURE_2D, 0, GL_ATC_RGB_AMD, uiWidth, uiHeight, 0, uiSize, pvData);


    ATC texture performance

For my test case setup, read blog post on ETC1 texture performance. The only difference is that these results are from a Nexus One which has an Adreno 200 instead of the PowerVR SGX on my Milestone. These are the results I got:

Framerate Size First load Reload RGB/RGBA 43.1 fps 6.0 MB ~376 ms ~251 ms ETC1/ETC1 + A 42.6 fps 1.9 MB ~142 ms ~174 ms ATCRGB/ATCRGBA 43.2 fps 1.4 MB ~143 ms ~128 ms

These results are very interesting, they show that the graphics architecture of the Nexus One is vastly different from that of the Milestone. There is absolutely no performance hit to using uncompressed textures, compared to a setup that was giving me a 13-33 fps difference between compressed and uncompressed on my Milestone. It's definitely worth using compressed textures for the file size difference, but unless your game has some crazy-complex textures you'll probably be fine with the more compatible ETC1 format.

However, one thing I will mention is that the ATC texture format is subjectively 'better looking' than the ETC1 format (to my eyes anyway). This is possibly due to better hardware decoding/interpolation support. When I manage to get my hands on a phone that supports S3TC I think I'll do an in-depth visual quality comparison between the four formats.

Next time I will show you how to find free 2D game art.

    Threading setup for an Android OpenGL Game
    
I'm not going to go into too much detail about how to setup your thread organization other than to say that for performance reasons you need an update thread separate from your render thread, because eglSwapBuffers() is a blocking call on the render thread. For an in-depth discussion of how to structure things check out Rendering With Two Threads.

My basic plan is to have an update thread running at 60 fps (to minimize input lag) and my render thread running at 30 fps. My render thread will grab the latest snapshot from the update thread when it begins and then use this information to build the graphics primitives and upload them to the GPU. I may also have a separate thread to handle audio updates and streaming, but I'll deal with that later when I've actually implemented audio.


    Creating POSIX threads

#include <pthread.h> pthread_t gMainPThread; pthread_attr_t gThreadAttribute; volatile bool MainThread::mbQuit = false; void* MainThread::ThreadEntry(void* _pvArg) { while (!mbQuit) { // Force 60.0 fps (this is temporary) usleep(16666); } return NULL; } void Java_com_brokenteapot_firstgame_FirstGame_JNIOnResume(JNIEnv* env, void* reserved) { // Tell thread to run continuously MainThread::mbQuit = false; // Create the thread pthread_attr_init(&gThreadAttribute); pthread_attr_setdetachstate(&gThreadAttribute, PTHREAD_CREATE_JOINABLE); pthread_create(&gMainPThread, &gThreadAttribute, &MainThread::ThreadEntry, NULL); } void Java_com_brokenteapot_firstgame_FirstGame_JNIOnPause(JNIEnv* env, void* reserved) { // Tell thread to quit MainThread::mbQuit = true; // Wait for thread to shutdown completely before continuing pthread_join(gMainPThread, NULL); pthread_attr_destroy(&gThreadAttribute); }

You'll notice right away that I'm doing something pretty weird; I'm creating/destroying my threads in OnResume/OnPause. If you look at the application lifecycle graph you'd assume the best place to create and destroy a thread would be in onCreate/onDestroy. But, there is no guarantee that either onStop or onDestroy is ever called! There are some sneaky little lines on the left side of the graph that lead directly to "Process is killed". This is really atrocious design, why even have states that can randomly never be called? What code would you possibly want to put in them? I'm sure there's a good reason for the way this is set up, but for now it eludes me... So anyway, I decided to create/kill my update thread in onResume/onPause because I am guaranteed that these states will be called every time my application is run. The initial state of the threads is set up in onCreate.


    Mutual exclusion (critical section)

pthread_mutex_t gCritical = PTHREAD_MUTEX_INITIALIZER; pthread_mutex_lock(&gCritical); /* Do non-thread-safe processing here */ pthread_mutex_unlock(&gCritical);


    Thread communication (semaphores)

pthread_mutex_t gCritical = PTHREAD_MUTEX_INITIALIZER; pthread_cond_t gSemaphore = PTHREAD_COND_INITIALIZER; void HelperThread() { pthread_mutex_lock(&gCritical); while (true) { // Wait for singal from main thread (critical section must be acquired) pthread_cond_wait(&gSemaphore, &gCritical); /* Do processing */ } pthread_mutex_unlock(&gCritical); } void MainThread() { // Signal semaphore (only after acquiring critical section) pthread_mutex_lock(&gCritical); pthread_cond_signal(&gSemaphore); pthread_mutex_unlock(&gCritical); }


    Thread local storage

pthread_key_t gThreadIDKey = INVALID; pthread_key_create(&gThreadIDKey, NULL); // In main thread static const int siMainThreadID = 0; pthread_setspecific(gThreadIDKey, &siMainThreadID); // In render thread static const int siRenderThreadID = 1; pthread_setspecific(gThreadIDKey, &siRenderThreadID); // If you need the thread ID later int* piThreadID = pthread_getspecific(gThreadIDKey);
 

Next time I will explain ATITC (ATC) texture encoding and performance.

What is a game without interaction? It's time to start accepting input!

    Touch Screen
   
This is the important one! Because the trackball and keyboard are not supported by every phone, your game needs to be playable and navigable using only the touchscreen.

import android.view.View; import android.view.MotionEvent; public class FirstGame extends Activity { @Override public boolean onTouchEvent(MotionEvent event) { switch (event.getAction()) { case MotionEvent.ACTION_DOWN: Log.d("JAVA_DEBUGGING", "Down " + event.getX() + " " + event.getY()); break; case MotionEvent.ACTION_MOVE: Log.d("JAVA_DEBUGGING", "Move " + event.getX() + " " + event.getY()); break; case MotionEvent.ACTION_UP: Log.d("JAVA_DEBUGGING", "Up " + event.getX() + " " + event.getY()); break; } return true; } }


    Intercept key-presses (back/menu/search)
   
Every Android phone has 4 physical buttons on the front: back, menu, home, and search (although not necessarily in that order). For a game it's a good idea to override the back button and insert an "Are you sure you want to quit?" dialog box. And obviously the menu button should be there to expose more advanced options to your power users (basic options can be put directly in the front-screen menu). For now I'm just using the physical buttons for debug input, I'll probably cover their actual in-game use in more detail later when I actually have a menu and proper back handling.

import android.view.Menu; public class FirstGame extends Activity { @Override public void onBackPressed() { Log.d("JAVA_DEBUGGING", "onBackPressed\n"); return; } @Override public boolean onCreateOptionsMenu(Menu menu) { Log.d("JAVA_DEBUGGING", "onCreateOptionsMenu\n"); return false; } @Override public boolean onSearchRequested() { Log.d("JAVA_DEBUGGING", "onSearchRequested\n"); return false; } }


    Override home button?

You can't! Unless you're writing a full home replacement (like AWD launcher for example). It's very important for a user to have a 'safety button' that can always return him to his home screen, otherwise it would be possible for a malicious application to completely take over a user's phone.

    Hardware Keyboard
   
The first thing you will want to do for phones with hardware keyboards is to stop your application from restarting when the user opens the hardware keyboard. For regular applications this is important to properly re-set the visual formatting, but for a game that has a fixed landscape orientation you definitely don't want this to occur.

import android.view.KeyEvent; public class FirstGame extends Activity { @Override public boolean onKeyDown(int keyCode, KeyEvent event) { // Ignore automatic repeats if (event.getRepeatCount() > 0) return super.onKeyDown(keyCode, event); // Handle basic human-readable keys if (event.isPrintingKey()) { Log.d("JAVA_DEBUGGING", "onKeyDown(" + keyCode +", '" + event.getDisplayLabel() + "')"); return true; } // Handle DPAD switch (keyCode) { case KeyEvent.KEYCODE_DPAD_CENTER: Log.d("JAVA_DEBUGGING", "DPAD Center"); return true; case KeyEvent.KEYCODE_DPAD_DOWN: Log.d("JAVA_DEBUGGING", "DPAD Down"); return true; case KeyEvent.KEYCODE_DPAD_LEFT: Log.d("JAVA_DEBUGGING", "DPAD Left"); return true; case KeyEvent.KEYCODE_DPAD_RIGHT: Log.d("JAVA_DEBUGGING", "DPAD Right"); return true; case KeyEvent.KEYCODE_DPAD_UP: Log.d("JAVA_DEBUGGING", "DPAD Up"); return true; } return super.onKeyDown(keyCode, event); } @Override public boolean onKeyUp(int keyCode, KeyEvent event) { return super.onKeyUp(keyCode, event); } }

Next time I'll explain how to use POSIX threads on Android.

    Delta Time
    
To profile the framerate of your game, you'll have to query the high resolution timer supported by your hardware. On Android you can use the clock_gettime call to get the current time:

static struct timespec lastTime; clock_gettime(CLOCK_MONOTONIC, &lastTime);

This call returns the number of hardware ticks since the start of your application. By itself this number is useless of course, you need to compare it to the time from the previous frame:

inline long TimeDifference(const struct timespec& last, const struct timespec& current) { // Note: There are 1000000000 nanoseconds in each second if (current.tv_sec > last.tv_sec) return (1000000000 - last.tv_nsec) + current.tv_nsec; else return current.tv_nsec - last.tv_nsec; } struct timespec currTime; clock_gettime(CLOCK_MONOTONIC, &currTime); long iNanoSeconds = TimeDifference(&lastTime, &currTime); lastTime = currTime;

Because a timespec is a 64-bit type, if you just compared the number of nanoseconds from frame to frame, tv_nsec would eventually overflow and you one frame you'd have a large negative time delta.


    Full-screen and forced landscape orientation
   
Use the following code to fully full-screen your game, and also to force landscape orientation.

import android.view.Window; import android.view.WindowManager; import android.content.pm.ActivityInfo; @Override public void onCreate(Bundle savedInstanceState) { ... // Set window fullscreen and remove title bar, and force landscape orientation this.requestWindowFeature(Window.FEATURE_NO_TITLE); getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN); setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE); ... }


    Prevent application restart on orientation change

Warning: The following code doesn't seem to play well with OpenGL ES 2.0 and the GLSurfaceView (API version 2.2). On my Nexus One the OpenGL surface does not get re-created and it causes the renderer to blit garbage onto the screen.

Add the following android:configChanges to your AndroidManifest.xml

<activity android:name=".FirstGame" android:label="@string/app_name" android:configChanges="orientation|keyboardHidden">

Override onConfigurationChanged in your Activity to prevent application restart

@Override public void onConfigurationChanged(final Configuration newConfig) { // Ignore orientation change to keep activity from restarting super.onConfigurationChanged(newConfig); }


    A random error message

After having my workflow working fairly well for over a month, I randomly started receiving the following error message: "The Program can't start because AdbWinApi.dll is missing from your computer"

I'm just reproducing the solution here in case anyone ever Googles around for the same problem. My solution was to add the following to the end of my "Path" environment variable:

C:\SDK\Android\android-sdk\platform-tools;

Next time I will show you how to use the various types of input available to Android devices.
 

Every Android OpenGL ES 2.0 phone supports at least two texture formats: ETC1 and one of the three proprietary formats (PVRTC, ATITC and S3TC). My phone supports PVRTC, so I wanted to see what the trade-offs were vs. ETC1 texture performance.

Bear in mind, if you want to support one of the proprietary formats, you'll have to support the other two as well and hence deal with packing all three formats in your data and correctly detecting which type to use at run-time.


    Encoding PVRTC textures

The first step is to download and install PVRTexTool_2.08.28.0634.msi from the Imagination website (requires free registration). The command line tool PVRTexTool.exe can be found in C:\Program Files (x86)\Imagination Technologies\POWERVR SDK\PVRTexTool_2.08.28.0634\PVRTexToolCL\Windows_x86_32. Here is how to use the compressor:

PVRTexTool.exe -f OGLPVRTC2 -yflip0 -i test.png -o test.pvr ... OGLPVRTC4 ...

The first argument selects the format of the texture, either 2 bits-per-pixel or 4 bits-per-pixel. The second argument prevents it from automatically flipping the texture upside down (I had to do this to bring it in line with the texture orientation output by etc1tool.exe). And obviously the next two arguments are the input and output filenames.

The encoder automatically detects the alpha layer in your .png file and encodes the .pvr with or without the alpha channel. One thing to note is that the alpha layer is very low precision, which makes the edges of the texture very jagged.

The encoded file has the following header:

struct PVR_TEXTURE_HEADER { unsigned int dwHeaderSize; unsigned int dwHeight; unsigned int dwWidth; unsigned int dwMipMapCount; unsigned int dwpfFlags; unsigned int dwDataSize; unsigned int dwBitCount; unsigned int dwRBitMask; unsigned int dwGBitMask; unsigned int dwBBitMask; unsigned int dwAlphaBitMask; unsigned int dwPVR; unsigned int dwNumSurfs; };


    Loading PVRTC textures in OpenGL

Loading is super simple, it works exactly like it does with ETC1 textures. Simply substitute GL_COMPRESSED_RGB_PVRTC_4BPPV1_IMG, GL_COMPRESSED_RGBA_PVRTC_2BPPV1_IMG or GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG as needed:
    
glCompressedTexImage2D(GL_TEXTURE_2D, 0, GL_COMPRESSED_RGB_PVRTC_2BPPV1_IMG, uiWidth, uiHeight, 0, uiSize, pvData);

    PVRTC texture performance

For my test case setup, read my last blog post on ETC1 texture performance. These are the results I got:

Framerate Size First load Reload RGB/RGBA 13.0 fps 5.9 MB ~1792 ms ~679 ms ETC1/ETC1 + A 29.4 fps 1.9 MB ~847 ms ~276 ms PRVCT4/PRVCT4A 29.4 fps 0.9 MB ~359 ms ~215 ms PRVCT2/PRVCT2A 33.3 fps 0.5 MB ~176 ms ~118 ms


    Conclusion

This confirms what I suspected, my phone has hardware support for decoding both ETC1 and PVRCT formats, and because I'm not texture bandwidth limited the extra alpha textures have a negligible impact. Using 2 bits-per-pixel PVRTC is not worth the reduced visual quality, and the small loading time gain with 4 bits-per-pixel is not worth the reduced alpha quality. I'll be sticking with ETC1 for this project.

Next time I'll show you how to force full-screen landscape orientation use the high-resolution timer (to measure framerate and delta time accurately), as well as other miscellaneous tips.