Freeglut on Android
===================
This platform is different than traditional desktop platforms, requiring
cross-compilation, interfacing with a touchscreen, and ability for your
application to be paused and resumed at any time.

Compiling
---------

  - Use your own cross-compiler for Android, or export the one from the Android
    NDK (API level 9 is required to use native activities): 

    /usr/src/android-ndk-r9d/build/tools/make-standalone-toolchain.sh \
      --platform=android-9 --install-dir=/usr/src/ndk-standalone-9

  - Compile freeglut and install it in your Android cross-compiler path:

    PATH=/usr/src/ndk-standalone-9/bin:$PATH
    cd /usr/src/freeglut-3.0/
    mkdir cross-android-gles/
    cd cross-android-gles/
    cmake \
      -D CMAKE_TOOLCHAIN_FILE=../android_toolchain.cmake \
      -D CMAKE_INSTALL_PREFIX=/usr/src/ndk-standalone-9/sysroot/usr \
      -D CMAKE_BUILD_TYPE=Debug \
      -D FREEGLUT_GLES=ON \
      -D FREEGLUT_BUILD_DEMOS=NO \
      ..
    make -j4
    make install
    # Only static for now:
    rm -f /usr/src/ndk-standalone-9/sysroot/usr/lib/libfreeglut-gles.so*

Using it in your projects
-------------------------

### Compile your own project using common build systems

For instance if you use the autotools:

    PATH=/usr/src/ndk-standalone-9/bin:$PATH
    export PKG_CONFIG_PATH=/usr/src/ndk-standalone-9/sysroot/usr/share/pkgconfig
    ./configure --host=arm-linux-androideabi --prefix=/somewhere
    make
    make install

If you use CMake, you may want to copy our Android toolchain 'android_toolchain.cmake':

    PATH="$PATH:/usr/src/android-ndk-r9d"
    PATH="$PATH:/usr/src/android-sdk-linux/tools"
    PATH="$PATH:/usr/src/android-sdk-linux/platform-tools"
    export PKG_CONFIG_PATH=/usr/src/ndk-standalone-9/sysroot/usr/share/pkgconfig
    cp .../freeglut-3.0/android_toolchain.cmake .
    mkdir cross-android/
    cd cross-android/
    cmake \
      -D CMAKE_TOOLCHAIN_FILE=../android_toolchain.cmake \
      -D CMAKE_INSTALL_PREFIX=/somewhere \
      -D CMAKE_BUILD_TYPE=Debug \
      -D MY_PROG_OPTION=something ... \
      ..
    make -j4
    make install

Check `progs/test-shapes-gles1/` in the freeglut source distribution for a
complete, stand-alone example.

### Compile your own project using the NDK build-system

  - Create a module hierarchy pointing to freeglut, with our Android.mk:

      mkdir freeglut-gles/
      cp .../freeglut-3.0/android/Android.mk freeglut-gles/
      ln -s /usr/src/ndk-standalone-9/sysroot/usr/include freeglut-gles/include
      ln -s /usr/src/ndk-standalone-9/sysroot/usr/lib freeglut-gles/lib

  - Reference this module in your jni/Android.mk:

      LOCAL_STATIC_LIBRARIES := ... freeglut-gles
      ...
      $(call import-module,freeglut-gles)

  - You now can point your NDK_MODULE_PATH to the directory containing the
    module: `ndk-build NDK_MODULE_PATH=.`

Notes
-----

  - Android never truly kills an application, even when pressing the Back
    button, even when the application is `onDestroy`'d: the process is still
    running and ready to accept `onCreate` event to become active again.
    By default, freeglut `exit()`s when the last window is closed (without
    returning to your main). But this behavior can be changed with
    `glutSetOption(GLUT_ACTION_ON_WINDOW_CLOSE, ...)`, in which case your have
    to either `exit()` yourself at the end of your main, or make sure your main
    can be called multiple times (in particular: beware of static variables that
    won't be reinitialized).

  - When a key is repeated, down and up events happen most often at the exact
    same time. This makes it impossible to animate based on key press time.
    e.g. down/up/wait/down/up rather than down/wait/down/wait/up This looks like
    a bug in the Android virtual keyboard system :/ Real buttons such as the
    Back button appear to work correctly (series of down events with proper
    getRepeatCount value). To work around this, freeglut provides its own
    minimal virtual keypad. It may be replaced by a virtual (touchscreen)
    joystick. 
