The Native Android API

Overview

Android exposes a native API to applications through the Native Development Kit (NDK). It is described in the $NDK/docs/STABLE-APIS.html document and summarized below:

Name Include Linking (LOCAL_LDLIBS :=...) Android version
C runtime library (libc) #include ... Automatic 1.5
Java Native Interface #include <jni.h> Automatic 1.5
Math #include <math.h> Automatic (-lm not needed) 1.5
POSIX Threads (pthreads) #include <pthread.h> Automatic (-lpthread not needed) 1.5
C++ #include .. Automatic (-lstdc++ not needed) 1.5
Android logging API #include <android/log.h> -llog 1.5
Zlib #include <zconf.h>
#include <zlib.h>
-lz 1.5
Dynamic linker #include <dlfcn.h> -ldl 1.5
OpenGL ES 1.x #include <GLES/gl.h>
#include <GLES/glext.h>
-lGLESv1_CM 1.6
OpenGL ES 2.0 #include <GLES2/gl2.h>
#include <GLES2/gl2ext.h>
-lGLESv2 2.0
Android bitmap API #include <android/bitmap.h> -ljnigraphics 2.2
EGL #include <EGL/egl.h>
#include <EGL/eglext.h>
#include <EGL/eglplatform.h>
-lEGL 2.3
OpenSL ES #include <SLES/OpenSLES.h>
#include <SLES/OpenSLES_Platform.h>
#include <SLES/OpenSLES_Android.h>
#include <SLES/OpenSLES_AndroidConfiguration.h>
-lOpenSLES 2.3
Android native application API Event loop:
#include <android/looper.h>

Input events:
#include <android/input.h>
#include <android/keycodes.h>

Sensor events:
#include <android/sensor.h>

Window/Surface management:
#include <android/rect.h>
#include <android/window.h>
#include <android/native_window.h>
#include <android/native_window_jni.h>

Assets:
#include <android/asset_manager.h>

Configuration:
#include <android/configuration.h>

OBB files:
#include <android/storage_manager.h>
#include <android/obb.h>

Native activity:
#include <android/native_activity.h>
-landroid 2.3
OpenMAX AL #include <OMXAL/OpenMAXAL.h>
#include <OMXAL/OpenMAXAL_Platform.h>
#include <OMXAL/OpenMAXAL_Android.h>
-lOpenMAXAL 4.0
OpenGL ES 3.0 #include <GLES3/gl3.h>
#include <GLES3/gl3ext.h>
-lGLESv3 4.3

Link Top

C runtime library (libc)

Android uses a custom C library named Bionic, which has a smaller API than a traditional Unix-like C library (it does not claim POSIX compliance). Generally, if one header is not there at build time, it's because its implementation is not available.

Link Top

Java Native Interface (JNI)

Android uses the same JNI as standard java. Three resources available online are the Java Native Interface Specification, the Programmer's Guide and Specification as well as Android JNI tips.

Link Top

POSIX threads (pthreads)

The android libc, bionic, provides built-in support for pthreads, so no additional linking (-lpthreads) is necessary. It does not implement full POSIX threads functionality and leaves out support for read/write locks, pthread_cancel(), process-shared mutexes and condition variables as well as other more advanced features. Read the bionic OVERVIEW.txt for more information.

TLS, thread-local storage, is limited to 59 pthread_key_t slots available to applications, lower than the posix minimum of 128.

Link Top

C++

The Android default system C++ runtime is a small C++ subset (e.g. no std::string or std::vector) limited to the following headers: cassert cctype cerrno cfloat climits cmath csetjmp csignal cstddef cstdint cstdio cstdlib cstring ctime cwchar new stl_pair.h typeinfo utility.

More complete C++ runtimes can be bundled with the application using either shared or static versions of STLport or the GNU Standard C++ Library provided with the NDK - see $NDK/docs/CPLUSPLUS-SUPPORT.html for more information.

By default both RTTI (Run-Time Type Information) and exceptions are disabled, but can be enabled with flags in either Application.mk or Android.mk:

APP_CPPFLAGS += -frtti     # Enable RTTI in Application.mk
LOCAL_CPP_FEATURES += rtti # Enable exceptions in Android.mk

APP_CPPFLAGS += -fexceptions     # Enable exceptions in Application.mk
LOCAL_CPP_FEATURES += exceptions # Enable exceptions in Android.mk

Note that the default system C++ runtime does not have exception or RTTI support - use another of the above mentioned C++ runtimes for that.

Link Top

Android logging API

The native logging API is defined in <android/log.h> and matches that of the java android.util.Log class:

Using variadic macros one may write portable logging such as:

Link Top

Zlib

The standard zlib compression library may be used by linking with libz.

Link Top

Dynamic linker

The dynamic linking functions dlopen(), dlsym(), dlclose() and dlerror() may be used by linking with libdl.

Link Top

OpenGL ES

Android support for OpenGL ES, a subset of OpenGL, is exposed both in Java and native API.

All android devices supports version OpenGL ES version 1.0, though some may use a software renderer. Applications which requires (as opposed to may optionally use features from through runtime checks) a higher version must specify so in their AndroidManifest.xml file with the android:glEsVersion attribute on the <uses-feature/> tag, as a 32-bit number with the higher and lower 16 bits representing the major and minor OpenGL version number:

<-- require OpenGL ES version 1.0 (default) -->
<uses-feature android:glEsVersion="0x00010000"/>

<-- require OpenGL ES version 1.1 -->
<uses-feature android:glEsVersion="0x00010001"/>

<-- require OpenGL ES version 2.0 -->
<uses-feature android:glEsVersion="0x00020000"/>

<-- require OpenGL ES version 3.0 -->
<uses-feature android:glEsVersion="0x00030000"/>

Note that the Android emulator does not support OpenGL ES version 3.x - a physical device is required for testing applications using that version.

Link Top

Android bitmap API

The API for handling android.util.Bitmap instances from native code is defined in <android/bitmap.h>:

Link Top

EGL

EGL (http://www.khronos.org/egl) exposes API to list supported EGL configurations, allocate and release OpenGLES surfaces and swap/flip surfaces for display (eglSwapBuffers).

Link Top

OpenSL ES

The OpenSL ES audio API, as well as some Android-specific extensions, is supported since Android version 2.3. The OpenSL ES 1.0.1 specification is bundled with the NDK under $NDK/docs/opensles/OpenSL_ES_Specification_1.0.1.pdf and Android-specific information is available under $NDK/docs/opensles/index.html.

Link Top

Android native application API

The Android native application API is an umbrella for accessing Android functionality otherwise exposed in java, all contained in a shared library named libandroid.so.

Link Top

Event loop

The ALooper struct is a native equivalent of the android.os.Looper java class and provides a basic event loop.

Link Top

Input events

Support for reading touch and key input from native code is defined in <android/input.h>, with keycodes available in <android/keycodes.h>. Note that this is only available when using NativeActivity (otherwise the java input API must be used).

Link Top

Sensor events

The API defined in <android/sensor.h> gives access to accelerometers, magnetic field, gyroscope, light and proximity sensors. See also the Sensors Overview for further information and best practices regarding sensors on Android.

Link Top

Window management

The API for handling android.view.Surface instances from native code, or "window management functions", is described by the below interfaces from <android/rect.h>, <android/native_window.h> and <android/native_window_jni.h>:

Link Top

Assets

Files in the assets/ folder can be accessed through AAssetManager, a native counterpart to the android.content.res.AssetManager java class described by the <android/asset_manager.h>:

Link Top

Configuration

Native API corresponding to the android.content.res.Configuration java class is available in <android/configuration.h>.

Link Top

OBB files

Native code can access OBB, Opaque Binary Blob files using API in <android/storage_manager.h> and <android/obb.h>.

Link Top

Native activity

The android.app.NativeActivity java class and the corresponding native struct ANativeActivity defined in <android/native_activity.h> frees applications from having to write java glue code, as well as providing native input event support not available otherwise. See $NDK/docs/NATIVE-ACTIVITY.HTML. Note the bundled utility android_native_app_glue.h and android_native_app_glue.c which implements an event loop in a separate thread receiving events from the main thread using a pipe.

Top

OpenMAX AL

See $NDK/docs/openmaxal/index.html and the bundled OpenMAX AL 1.0.1 specification for information about using this multimedia API.