| <h1>Android NDK Stable APIs:</h1> |
| <p>This is the list of stable APIs/ABIs exposed by the Android NDK.</p> |
| <h2>I. Purpose:</h2> |
| <p>Each API corresponds to a set of headers files, and a shared library file |
| that contains the corresponding implementation, and which must be linked |
| against by your native code.</p> |
| <p>For example, to use system library "Foo", you would include a header |
| like <foo.h> in your code, then tell the build system that your native |
| module needs to link to /system/lib/libfoo.so at load-time by adding |
| the following line to your Android.mk file:</p> |
| <p><code>LOCAL_LDLIBS</code> := <code>-lfoo</code></p> |
| <p>Note that the build system automatically links the C library, the Math |
| library and the C++ support library to your native code, there is no |
| need to list them in a <code>LOCAL_LDLIBS</code> line.</p> |
| <p>There are several "API Levels" defined. Each API level corresponds to |
| a given Android system platform release. The following levels are |
| currently supported:</p> |
| <pre><code> android-3 -> Official Android 1.5 system images |
| android-4 -> Official Android 1.6 system images |
| android-5 -> Official Android 2.0 system images |
| android-6 -> Official Android 2.0.1 system images |
| android-7 -> Official Android 2.1 system images |
| android-8 -> Official Android 2.2 system images |
| android-9 -> Official Android 2.3 system images |
| android-14 -> Official Android 4.0 system images |
| android-18 -> Official Android 4.3 system images |
| </code></pre> |
| <p>Note that android-6 and android-7 are the same as android-5 for the NDK, |
| i.e. they provide exactly the same native ABIs!</p> |
| <p>IMPORTANT:</p> |
| <blockquote> |
| <p>The headers corresponding to a given API level are now located |
| under $NDK/platforms/android-<level>/arch-arm/usr/include</p> |
| </blockquote> |
| <h2>II. Android-3 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that |
| runs on Android 1.5 system images and above.</p> |
| <h3>The C Library:</h3> |
| <p>The C library headers, as they are defined on Android 1.5 are available |
| through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header |
| is not there at build time, it's because its implementation is not available |
| on a 1.5 system image.</p> |
| <p>The build system automatically links your native modules to the C library, |
| you don't need to add it to <code>LOCAL_LDLIBS</code>.</p> |
| <p>Note that the Android C library includes support for pthread (<pthread.h>), |
| so "LOCAL_LIBS := <code>-lpthread"</code> is not needed. The same is true for real-time |
| extensions (-lrt on typical Linux distributions).</p> |
| <pre><code>** VERY IMPORTANT NOTE: ****************************************************** |
| * |
| * The kernel-specific headers in <linux/...> and <asm/...> are not considered |
| * stable at this point. Avoid including them directly because some of them |
| * are likely to change in future releases of the platform. This is especially |
| * true for anything related to specific hardware definitions. |
| * |
| ****************************************************************************** |
| </code></pre> |
| <h3>The Math Library:</h3> |
| <p><code><math.h></code> is available, and the math library is automatically linked to your |
| native modules at build time, so there is no need to list "<code>-lm</code>" through |
| <code>LOCAL_LDLIBS</code>.</p> |
| <h3>C++ Library:</h3> |
| <p>An <em>extremely</em> minimal C++ support API is available. For Android 1.5, this is |
| currently limited to the following headers:</p> |
| <pre><code> <cstddef> |
| <new> |
| <utility> |
| <stl_pair.h> |
| </code></pre> |
| <p>They may not contain all definitions required by the standard. Notably, |
| support for C++ exceptions and RTTI is not available with Android 1.5 system |
| images.</p> |
| <p>The C++ support library (-lstdc++) is automatically linked to your native |
| modules too, so there is no need to list it through <code>LOCAL_LDLIBS</code></p> |
| <h3>Android-specific Log Support:</h3> |
| <p><code><android/log.h></code> contains various definitions that can be used to send log |
| messages to the kernel from your native code. Please have a look at its |
| content in (<code>platforms/android-3/arch-arm/usr/include/android/log.h</code>), which |
| contain many informative comments on how to use it.</p> |
| <p>You should be able to write helpful wrapper macros for your own usage to |
| access this facility.</p> |
| <p>If you use it, your native module should link to /system/lib/liblog.so with:</p> |
| <pre><code> LOCAL_LDLIBS := -llog |
| </code></pre> |
| <h3>ZLib Compression Library:</h3> |
| <p><code><zlib.h></code> and <code><zconf.h></code> are available and can be used to use the ZLib |
| compression library. Documentation for it is at the ZLib page:</p> |
| <blockquote> |
| <p><a href="http://www.zlib.net/manual.html">http://www.zlib.net/manual.html</a></p> |
| </blockquote> |
| <p>If you use it, your native module should link to /system/lib/libz.so with:</p> |
| <pre><code> `LOCAL_LDLIBS` := `-lz` |
| </code></pre> |
| <h3>Dynamic Linker Library:</h3> |
| <p><code><dlfcn.h></code> is available and can be used to use the dlopen()/dlsym()/dlclose() |
| functions provided by the Android dynamic linker. You will need to link |
| against /system/lib/libdl.so with:</p> |
| <pre><code> `LOCAL_LDLIBS` := `-ldl` |
| </code></pre> |
| <h2>III. Android-4 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that runs |
| on Android 1.6 system images and above,</p> |
| <h3>The OpenGL ES 1.x Library:</h3> |
| <p>The standard OpenGL ES headers <code><GLES/gl.h></code> and <code><GLES/glext.h></code> contain the |
| declarations needed to perform OpenGL ES 1.x rendering calls from native |
| code.</p> |
| <p>If you use them, your native module should link to /system/lib/libGLESv1_CM.so |
| as in:</p> |
| <pre><code> `LOCAL_LDLIBS` := `-lGLESv1_CM` |
| </code></pre> |
| <p>The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs. |
| Please note that:</p> |
| <ul> |
| <li>OpenGL ES 1.0 is supported on <em>all</em> Android-based devices.</li> |
| <li>OpenGL ES 1.1 is fully supported only on specific devices that |
| have the corresponding GPU.</li> |
| </ul> |
| <p>This is because Android comes with a 1.0-capable software renderer that can |
| be used on GPU-less devices.</p> |
| <p>Developers should query the OpenGL ES version string and extension string |
| to know if the current device supports the features they need. See the |
| description of glGetString() in the specification to see how to do that:</p> |
| <blockquote> |
| <p><a href="http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml">http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml</a></p> |
| </blockquote> |
| <p>Additionally, developers must put a <code><uses-feature></code> tag in their manifest |
| file to indicate which version of OpenGL ES their application requires. See |
| the documentation linked below for details:</p> |
| <blockquote> |
| <p><a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">http://developer.android.com/guide/topics/manifest/uses-feature-element.html</a></p> |
| </blockquote> |
| <p>Please note that EGL APIs are only available starting from API level 9. You |
| can however perform the corresponding operations (surface creation and flipping) |
| by using the VM. For example, with a GLSurfaceView as described here:</p> |
| <blockquote> |
| <p><a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html">http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html</a></p> |
| </blockquote> |
| <p>The "san-angeles" sample application shows how you can do that, while |
| rendering each frame in native code. This is a small Android port of the |
| excellent "San Angeles Observation" demo program. For more information about |
| it, see:</p> |
| <blockquote> |
| <p><a href="http://jet.ro/visuals/san-angeles-observation/">http://jet.ro/visuals/san-angeles-observation/</a></p> |
| </blockquote> |
| <h2>IV. Android-5 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that runs |
| on Android 2.0 system images and above.</p> |
| <h3>The OpenGL ES 2.0 Library:</h3> |
| <p>The standard OpenGL ES 2.0 headers <code><GLES2/gl2.h></code> and <code><GLES2/gl2ext.h></code> contain the |
| declarations needed to perform OpenGL ES 2.0 rendering calls from native code. |
| This includes the ability to define and use vertex and fragment shaders using the |
| GLSL language.</p> |
| <p>If you use them, your native module should link to /system/lib/libGLESv2.so |
| as in:</p> |
| <pre><code> `LOCAL_LDLIBS` := `-lGLESv2` |
| </code></pre> |
| <p>Not all devices support OpenGL ES 2.0, developers should thus query the |
| implementation's version and extension strings, and put a <code><uses-feature></code> |
| tag in their Android manifest. See Section III above for details.</p> |
| <p>Please note that EGL APIs are only available starting from API level 9.</p> |
| <p>The "hello-gl2" sample application demonstrate this. It is used to draw a very |
| simple triangle with the help of a vertex and fragment shaders.</p> |
| <p>IMPORTANT NOTE:</p> |
| <blockquote> |
| <p>The Android emulator does not support OpenGL ES 2.0 hardware emulation |
| at this time. Running and testing code that uses this API requires a |
| real device with such capabilities.</p> |
| </blockquote> |
| <h2>IV. Android-8 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that runs |
| on Android 2.2 system images and above.</p> |
| <h3>The 'jnigraphics' Library:</h3> |
| <p>This is a tiny library that exposes a stable, C-based, interface that allows |
| native code to reliably access the pixel buffers of Java bitmap objects.</p> |
| <p>To use it, include the <code><android/bitmap.h></code> header in your source code, and |
| and link to the jnigraphics library as in:</p> |
| <pre><code> `LOCAL_LDLIBS` += `-ljnigraphics` |
| </code></pre> |
| <p>For details, read the source header at the following location:</p> |
| <pre><code> platforms/android-8/arch-arm/usr/include/android/bitmap.h |
| </code></pre> |
| <p>Briefly, typical usage should look like:</p> |
| <ol> |
| <li> |
| <p>Use <code>AndroidBitmap_getInfo()</code> to retrieve information about a |
| given bitmap handle from JNI (e.g. its width/height/pixel format)</p> |
| </li> |
| <li> |
| <p>Use <code>AndroidBitmap_lockPixels()</code> to lock the pixel buffer and |
| retrieve a pointer to it. This ensures the pixels will not move |
| until <code>AndroidBitmap_unlockPixels()</code> is called.</p> |
| </li> |
| <li> |
| <p>Modify the pixel buffer, according to its pixel format, width, |
| stride, etc.., in native code.</p> |
| </li> |
| <li> |
| <p>Call <code>AndroidBitmap_unlockPixels()</code> to unlock the buffer.</p> |
| </li> |
| </ol> |
| <h2>V. Android-9 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that runs |
| on Android > 2.3 system images and above.</p> |
| <h3>The EGL graphics library:</h3> |
| <p>EGL provides a native platform interface to allocate and manage OpenGLES |
| surfaces. For more information about its features, please see:</p> |
| <blockquote> |
| <p><a href="http://www.khronos.org/egl">http://www.khronos.org/egl</a></p> |
| </blockquote> |
| <p>In a nutshell, this will allow you to do the following directly from |
| native code:</p> |
| <ul> |
| <li>List supported EGL configurations</li> |
| <li>Allocate and release OpenGLES surfaces</li> |
| <li>Swap/Flip surfaces for display (eglSwapBuffers)</li> |
| </ul> |
| <p>This is provided through the following headers:</p> |
| <pre><code> <EGL/egl.h> -> Main EGL API definitions |
| <EGL/eglext.h> -> EGL extension-related definitions |
| </code></pre> |
| <p>You cal link against the system's EGL library by adding the following |
| to your NDK module definition:</p> |
| <pre><code> LOCAL_LDLIBS += -lEGL |
| </code></pre> |
| <h3>The OpenSL ES native audio Library:</h3> |
| <p>Android native audio is based on Khronos Group OpenSL ES™ 1.0.1.</p> |
| <p>The standard OpenSL ES headers <code><SLES/OpenSLES.h></code> and <code><SLES/OpenSLES_Platform.h></code> |
| contain the declarations needed to perform audio input and output from the |
| native side of Android.</p> |
| <p>NOTE: Despite the fact that the OpenSL ES 1.0.1 specification uses |
| <code><OpenSLES.h></code> to include these headers, Khronos has modified later versions of |
| the document to recommend <code><SLES/OpenSLES.h></code> instead, hence the later |
| approach was adopted for Android.</p> |
| <p>This API level also provides Android-specific extensions, see the content |
| of <code><SLES/OpenSLES_Android.h></code> and <code><SLES/OpenSLES_AndroidConfiguration.h></code> for |
| details.</p> |
| <p>The system library named "libOpenSLES.so" implements the public native audio |
| functions. Use the following to link your modules against it:</p> |
| <pre><code> LOCAL_LDLIBS += -lOpenSLES |
| </code></pre> |
| <p>For more information about this topic, please read the document docs/opensles/index.html.</p> |
| <h3>The Android native application APIs:</h3> |
| <p>Starting from API level 9, it is possible to entirely write an Android |
| application with native code (i.e. without any Java). That does not mean |
| that your code does not run inside a VM though, and most of the features |
| of the platform will still need to be accessed through JNI.</p> |
| <p>For more information about this topic, please read the dedicated |
| document named <a href="NATIVE-ACTIVITY.html">NATIVE-ACTIVITY</a></p> |
| <p>The following headers correspond to these new native APIs (see comments |
| inside them for more details):</p> |
| <ul> |
| <li> |
| <p><code><android/native_activity.h></code></p> |
| <blockquote> |
| <p>Activity lifecycle management (and general entry point)</p> |
| </blockquote> |
| </li> |
| <li> |
| <p><code><android/looper.h></code><br> |
| <code><android/input.h></code><br> |
| <code><android/keycodes.h></code><br> |
| <code><android/sensor.h></code></p> |
| <blockquote> |
| <p>To Listen to input events and sensors directly from native code.</p> |
| </blockquote> |
| </li> |
| <li> |
| <p><code><android/rect.h></code><br> |
| <code><android/window.h></code><br> |
| <code><android/native_window.h></code><br> |
| <code><android/native_window_jni.h></code></p> |
| <blockquote> |
| <p>Window management, including the ability to lock/unlock the pixel |
| buffer to draw directly into it.</p> |
| </blockquote> |
| </li> |
| <li> |
| <p><code><android/configuration.h></code><br> |
| <code><android/asset_manager.h></code><br> |
| <code><android/storage_manager.h></code><br> |
| <code><android/obb.h></code></p> |
| <blockquote> |
| <p>Direct (read-only) access to assets embedded in your .apk. or |
| the Opaque Binary Blob (OBB) files, a new feature of Android X.X |
| that allows one to distribute large amount of application data |
| outside of the .apk (useful for game assets, for example).</p> |
| </blockquote> |
| </li> |
| </ul> |
| <p>All the corresponding functions are provided by the "libandroid.so" library |
| version that comes with API level 9. To use it, use the following:</p> |
| <pre><code> LOCAL_LDLIBS += -landroid |
| </code></pre> |
| <h2>VI. Android-14 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that runs |
| on Android > 4.0 system images and above.</p> |
| <h3>The OpenMAX AL native multimedia library:</h3> |
| <p>Android native multimedia is based on Khronos Group OpenMAX AL™ 1.0.1.</p> |
| <p>The standard OpenMAX AL headers <code><OMXAL/OpenMAXAL.h></code> and <code><OMXAL/OpenMAXAL_Platform.h></code> |
| contain the declarations needed to perform multimedia output from the |
| native side of Android.</p> |
| <p>NOTE: Despite the fact that the OpenMAX AL 1.0.1 specification uses |
| <code><OpenMAXAL.h></code> to include these headers, Khronos has modified later versions of |
| the document to recommend <code><OMXAL/OpenMAXAL.h></code> instead, hence the later |
| approach was adopted for Android.</p> |
| <p>This API level also provides Android-specific extensions, see the content |
| of <code><OMXAL/OpenMAXAL_Android.h></code> for details.</p> |
| <p>The system library named "<code>libOpenMAXAL.so</code>" implements the public native multimedia |
| functions. Use the following to link your modules against it:</p> |
| <pre><code> LOCAL_LDLIBS += -lOpenMAXAL |
| </code></pre> |
| <p>For more information about this topic, please read the document docs/openmaxal/index.html.</p> |
| <h3>The OpenSL ES native audio library:</h3> |
| <p>Native audio APIs based on OpenSL ES were added in API level 9. |
| Starting with API level 14, the native audio API was extended to support |
| decoding to PCM. See section "The OpenSL ES native audio Library" |
| above for a high-level summary of how to use OpenSL ES, and the details |
| in docs/opensles/index.html.</p> |
| <h2>V. Android-18 Stable Native APIs:</h2> |
| <p>All the APIs listed below are available for developing native code that runs |
| on Android 4.3 system images and above.</p> |
| <h3>The OpenGL ES 3.0 Library:</h3> |
| <p>The standard OpenGL ES 3.0 headers <code><GLES3/gl3.h></code> and <code><GLES3/gl3ext.h></code> contain the |
| declarations needed to perform OpenGL ES 3.0 rendering calls from native code.</p> |
| <p>If you use them, your native module should link to /system/lib/libGLESv3.so |
| as in:</p> |
| <p><code>LOCAL_LDLIBS</code> := <code>-lGLESv3</code></p> |
| <p>Not all devices support OpenGL ES 3.0, developers should thus query the |
| implementation's version and extension strings, and put a <code><uses-feature></code> |
| tag in their Android manifest. See Section III above for details.</p> |
| <p>The "gles3jni" sample application demonstrate this.</p> |
| <p>IMPORTANT NOTE:</p> |
| <blockquote> |
| <p>The Android emulator does not support OpenGL ES 3.0 hardware emulation |
| at this time. Running and testing code that uses this API requires a |
| real device with such capabilities.</p> |
| </blockquote> |
