Version 4 (modified by jizquierdo, 3 years ago)

Final editing for revision

Building and using OpenSceneGraph in Android

Requirements to compile OpenSceneGraph for Android

Note:

While Android-sdk version doesn't really matter, ndk version is need to be 4(Crystax Version) 5 or 5b. We expect that newer versions will work but that is something to come.

Build config

When working in Android you have to set OSG to work in GLES1 OR GLES2 it's not advisable to compile with support for both libraries at the same time. Runtime linking errors can happen. If you don't know how to set GLES1/2 please read OpenGL-ES in OSG wiki.

CMake building script will search the Ndk (With the original name as it is in google releases) in $HOME or $HOME/android_development.Otherwise you can set manually where it is with the environment variable: ANDROID_NDK.

When you call CMake you need to set the variable: OSG_BUILD_PLATFORM_ANDROID to on and DYNAMIC_OPENTHREADS / DYNAMIC_OPENSCENEGRAPH to off. The first variable enables the compilation for android because we are doing something similar to cross-compiling. The other two make OpenSceneGraph to compile statically. At the moment the build config generated for android only contemplates a static build not a dynamic one. The main reason is that you cannot "install" as it is the dynamic libraries onto your phone so all of them have to be in your apk. At the same time Google in their last ndk only supports RTTI and exceptions if you use gnu_static_stl. That would increase dramatically every dynamic library size.

So if you want to build a OSG with OpenGL ES 1.x you need to use the next line (supposing out-of-source build).

cmake .. -DOSG_BUILD_PLATFORM_ANDROID=ON -DDYNAMIC_OPENTHREADS=OFF
-DDYNAMIC_OPENSCENEGRAPH=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
-DOSG_CPP_EXCEPTIONS_AVAILABLE=OFF

That will generate every Android Makefile needed to compile OSG for Android. Once that process is finished a Make will start compilation.

If you want to use -j option to speed build note that you can't use it from make command because our make will call ndk-build. To set the j level You have to set it in the cmake config line with the variable J (-DJ=2). We decided to use Android Makefiles to ensure the most possible compatibility between ndk changes instead of a straightforward crosscompiling. Because of that there are some standard options that don't work quite well, don't work at all or simply need more time and debugging.

One of the options that don't work right now is make install so you will need to copy or point from your final program to the headers. Remember that OSG and OpenThreads? use a Config file that will be stored in the directory you have generated CMake build commands instead of the normal headers.

If you don't want to use the normal make and instead use directly ndk-build you can do so. This makes accessible more info of the building process, compiler calls and other things.

$ $ANDROID_NDK/ndk_build NDK_APPLICATION_MK=Application.mk [OPTIONS]

NDK-Build useful options

NDK_DEBUG=1generate debuggable native code
V=1launch build, displaying build commands
-Bforce a complete rebuild
NDK_LOG=1display internal NDK log messages

For more info please read the documentation inside your ndk.

Building your Application

In the last compilation chain we've included every serializer and deprecated to support .osg models. As stated before, please, be aware that this doesn't mean that everything works. In the latest test we concluded that right now osgSim and osgShadow don't work or make the screen Black. OpenGL ES 2.0 it's still in testing.

By default we build OSG against Android/platform-5 this can be overridden in Application.mk before compiling. Do not try to compile in Platforms less than 5 it's not advisable even if you can. Remember Platform-5 are Android Devices with 2.0 and works with newer versions. In your program please remember to link all the libraries you need in the Android.mk and be careful with the order or you will receive compiling errors. The example program is a good point to start your program if you are not aware of those details.

As now we haven't enabled armeabi-v7 nor Neon extension to make it easier for testing. If you want to use them in your program you'll need to recompile osg and change the makefile configuration to use them. Remember that armeabi (v5) works in v7. Certainly v7 is faster but can't run on devices that are v5.

If you are not confident in building your own project with ndk you can use Eclipse and install ndk assistance plugins (there are three or four of them) If not you can use the console with the standard commands as stated in: http://developer.android.com/sdk/ndk/overview.html#samples You can start from the provided osgViewerGles1Android example that we've provided as a start. Remember to change and set up properly your include and binaries directories. The example program has the same egl start context as google's ndk examples and some code to get out virtual keyboards, masking of standard keys (the program will only close with home) and the code need to pass screen/keyboard events to OpenSceneGraph like mouse/keyboard. Multitouch is masked as mouse events instead of using the multitouch approach. We support using double tap to move, simple move to drag and pinch to zoom. We support as well a double tap (in different locations) to make a reset of the view.

Finally remember that OSG in android is a STATIC build so if you don't use the macros he won't know what plugins and serializers are or not enabled. The macro are: USE_OSGPLUGIN(name_plugin) USE_DOTOSGWRAPPER_LIBRARY(name_deprecated) USE_SERIALIZER_WRAPPER_LIBRARY(name_serializer)

3rd Party Dependencies

At this moment we only compile Plugins that do not requiere any 3rd dependency. But we expect to enable all that can be used with linux in no time. If you have enough expertise you can compile static any 3rd dependency and enable the compiling of the plugin that you need. Currently have been tested and work successfully: libjpg libpng libtiff libcurl freetype