This file contents can be applied for version OpenSceneGraph(OSG) 3.0.2 or newer.

Prerequisites for build process

To compile OSG as a standalone library you'll only need the Android NDK. To develop applications with the library you'll also need the Android SDK

• Android SDK: http://developer.android.com/sdk/index.html

• Android NDK: http://developer.android.com/sdk/ndk/index.html

The required version to compile OSG is NDK r5 or newer. We don't recommend using previous versions or modified versions although it's possible to use the Crystax NDK versions.

Device minimun requirements

OSG for Android need to use a Level 8 or newer Native ABI and a 2.2 or newer Android version. It's possible to use Android 2.1 devices succesfully but it's not recommended. Older Android versions are not supported. There are specific device models with a bug that need the application locked in landscape mode to run.

OpenSceneGraph Android known issues

OSG for Android is a STATIC build library

• To add a plugin or module you have to use the macros: USE_OSGPLUGIN(),USE_DOTOSGWRAPPER_LIBRARY(),USE_SERIALIZER_WRAPPER_LIBRARY().

• OSG for Android uses OpenGL ES 1.X/2.0.

• There are features present in OpenGL that doesn't exist in OpenGL ES: http://www.khronos.org/opengles/

• ENVIRONMENTAL MAPPING DOESN'T WORK but  you can use a E.M. Shader in GLES 2.0.

• OSG Pregenerated Shaders DON'T compile with GLES, you need to add your shaders.

Multithreaded Viewer CRASHES the application.

osgSim and osgShadow will crash the application if you don't link freetype.

Build Config

For the Android building in OSG, we use the CMake command line to generate the Android Makefiles. These are the variables that have to be set.

ANDROID BUILD

The first CMake variable to be set is the Android build Variable

-DOSG_BUILD_PLATFORM_ANDROID=ON

Now, CMake needs to know where you have the NDK. That's done by setting the next variable

-DANDROID_NDK={Path to your NDK root directory}

Right now, Android version has to be compiled in static. To do so you have to set the next variables.

-DDYNAMIC_OPENTHREADS=OFF

-DDYNAMIC_OPENSCENEGRAPH=OFF

OPENGL ES CONFIG

When working in Android, you have to set OSG in GLES1 OR GLES2 configuration. It's not advisable to compile with support for both at the same time. Runtime linking error may happen. To set GLES1/2 functionality you have to set the options in CMake:

GLES1

-DOSG_GL1_AVAILABLE=OFF

-DOSG_GL2_AVAILABLE=OFF

-DOSG_GL3_AVAILABLE=OFF

-DOSG_GLES1_AVAILABLE=ON

-DOSG_GLES2_AVAILABLE=OFF

-DOSG_GL_LIBRARY_STATIC=OFF

-DOSG_GL_DISPLAYLISTS_AVAILABLE=OFF

-DOSG_GL_MATRICES_AVAILABLE=ON

-DOSG_GL_VERTEX_FUNCS_AVAILABLE=ON

-DOSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLE=ON

-DOSG_GL_FIXED_FUNCTION_AVAILABLE=ON

GLES2 

-DOSG_GL1_AVAILABLE=OFF

-DOSG_GL2_AVAILABLE=OFF

-DOSG_GL3_AVAILABLE=OFF

-DOSG_GLES1_AVAILABLE=OFF

-DOSG_GLES2_AVAILABLE=ON

-DOSG_GL_LIBRARY_STATIC=OFF

-DOSG_GL_DISPLAYLISTS_AVAILABLE=OFF

-DOSG_GL_MATRICES_AVAILABLE=OFF

-DOSG_GL_VERTEX_FUNCS_AVAILABLE=OFF

-DOSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLE=OFF

-DOSG_GL_FIXED_FUNCTION_AVAILABLE=OFF

COMPILATION OPTIONS

You can select the Android ABI hardwares to be compiled (x86,armeabi,armeabi-v7a,mips) This option is set by default to armeabi armeabi-v7a and the ABI platform version. This option is set by default to 5.

-DANDROID_ABI "armeabi armeabi-v7a"

-DANDROID_PLATFORM=8

OSG requires the C++ STL library in Android there are several different STL versions static and shared. Which versión is used can be setted with the next variable. By default this variable is set to gnustl_static.

-DANDROID_STL="gnustl_static"

To generate the binary libraries with debug symbols you have to use the next variable.

-DANDROID_DEBUG

OPTIMIZATIONS

The next variables can be set to true to enable some optimizations. Beware that not all devices are compatible with them and not on all ABI platforms.

-DANDROID_OPTIM_NEON

-DANDROID_OPTIM_ARM32

OTHERS

To enable the -j command  you have to set it in the Cmake line.

-DJ=4

To define a install path you have to use the nex variable

-DCMAKE_INSTALL_PREFIX={install path}

Building your application

Building an application in Android withouth any prior knowledge is hard. If you don't have experience developing simple test Android NDK applications don't try to cope with OSG in Android. First learn some basics of Android/Dalvik and about Android/NDK. It's not recommendable to go to our mailing lists or google's withouth some knowledge first. For some good readins I can recommend the next books:

OPENSCENEGRAPH

Wang Rui et Al. OpenSceneGraph Beginners Guide Published

Wang Rui et Al. OpenSceneGraph Cookbook Published

ANDROID

Reto Meier Professional Android 4 Application Development

Sylvain Ratabouil Android NDK

Building an application with a native part in Android is a two step job. First you have to compile the native part with the ndk-build and second you need to compile the java part. There are some plugins in eclipse that ease this part like  Sequoyah. If you want to check how to do a OsgAndroid Application then there are two examples in the OSG distribution. They are for GLES1 and GLES2. This are the characteristics implemented in the application.

Resolution locked to landscape.

Menu button shows a Android menu with options to load or delete models, also you can use the virtual keyboard.

Basic state and manipulator changes by keyboard entry.

Android UI with buttons to center view and change mode of navigation.

Multitouch example.

Keep in mind that the examples are not fully native. They don't use the NativeActivity and so they rely on a JNI code to call the OSG functions from the Java side.

 3rd Party Dependencies

To ease the development of applications, there is a 3rd party dependency pack with libjpeg, libpng, libtiff, libcurl and freetype to use with OpenSceneGraph in Android. This pack only works with armeabi v5 and v7.  The package can be found at the next address: http://www2.ai2.upv.es/difusion/osgAndroid/3rdpartyAndroid.zip

To use the package,  put the 3rdparty directory inside the OSG root directory and run Cmake. It will be detected and configured appropiatedly.