433 lines
15 KiB
Plaintext
433 lines
15 KiB
Plaintext
Android NDK Stable APIs:
|
|
========================
|
|
|
|
This is the list of stable APIs/ABIs exposed by the Android NDK.
|
|
|
|
I. Purpose:
|
|
-----------
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
LOCAL_LDLIBS := -lfoo
|
|
|
|
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 LOCAL_LDLIBS line.
|
|
|
|
There are several "API Levels" defined. Each API level corresponds to
|
|
a given Android system platform release. The following levels are
|
|
currently supported:
|
|
|
|
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
|
|
|
|
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!
|
|
|
|
IMPORTANT:
|
|
> The headers corresponding to a given API level are now located
|
|
under $NDK/platforms/android-<level>/arch-arm/usr/include
|
|
|
|
|
|
II. Android-3 Stable Native APIs:
|
|
---------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that
|
|
runs on Android 1.5 system images and above.
|
|
|
|
### The C Library:
|
|
|
|
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.
|
|
|
|
The build system automatically links your native modules to the C library,
|
|
you don't need to add it to LOCAL_LDLIBS.
|
|
|
|
Note that the Android C library includes support for pthread (<pthread.h>),
|
|
so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time
|
|
extensions (-lrt on typical Linux distributions).
|
|
|
|
|
|
** 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.
|
|
*
|
|
******************************************************************************
|
|
|
|
|
|
### The Math Library:
|
|
|
|
`<math.h>` is available, and the math library is automatically linked to your
|
|
native modules at build time, so there is no need to list "`-lm`" through
|
|
LOCAL_LDLIBS.
|
|
|
|
|
|
|
|
### C++ Library:
|
|
|
|
An *extremely* minimal C++ support API is available. For Android 1.5, this is
|
|
currently limited to the following headers:
|
|
|
|
<cstddef>
|
|
<new>
|
|
<utility>
|
|
<stl_pair.h>
|
|
|
|
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.
|
|
|
|
The C++ support library (-lstdc++) is automatically linked to your native
|
|
modules too, so there is no need to list it through LOCAL_LDLIBS
|
|
|
|
|
|
|
|
### Android-specific Log Support:
|
|
|
|
`<android/log.h>` 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 (`platforms/android-3/arch-arm/usr/include/android/log.h`), which
|
|
contain many informative comments on how to use it.
|
|
|
|
You should be able to write helpful wrapper macros for your own usage to
|
|
access this facility.
|
|
|
|
If you use it, your native module should link to /system/lib/liblog.so with:
|
|
|
|
LOCAL_LDLIBS := -llog
|
|
|
|
|
|
### ZLib Compression Library:
|
|
|
|
`<zlib.h>` and `<zconf.h>` are available and can be used to use the ZLib
|
|
compression library. Documentation for it is at the ZLib page:
|
|
|
|
> http://www.zlib.net/manual.html
|
|
|
|
If you use it, your native module should link to /system/lib/libz.so with:
|
|
|
|
LOCAL_LDLIBS := -lz
|
|
|
|
|
|
### Dynamic Linker Library:
|
|
|
|
`<dlfcn.h>` 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:
|
|
|
|
LOCAL_LDLIBS := -ldl
|
|
|
|
|
|
III. Android-4 Stable Native APIs:
|
|
----------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that runs
|
|
on Android 1.6 system images and above,
|
|
|
|
|
|
### The OpenGL ES 1.x Library:
|
|
|
|
The standard OpenGL ES headers `<GLES/gl.h>` and `<GLES/glext.h>` contain the
|
|
declarations needed to perform OpenGL ES 1.x rendering calls from native
|
|
code.
|
|
|
|
If you use them, your native module should link to /system/lib/libGLESv1_CM.so
|
|
as in:
|
|
|
|
LOCAL_LDLIBS := -lGLESv1_CM
|
|
|
|
|
|
The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs.
|
|
Please note that:
|
|
|
|
- OpenGL ES 1.0 is supported on *all* Android-based devices.
|
|
- OpenGL ES 1.1 is fully supported only on specific devices that
|
|
have the corresponding GPU.
|
|
|
|
This is because Android comes with a 1.0-capable software renderer that can
|
|
be used on GPU-less devices.
|
|
|
|
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:
|
|
|
|
> http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml
|
|
|
|
Additionally, developers must put a `<uses-feature>` tag in their manifest
|
|
file to indicate which version of OpenGL ES their application requires. See
|
|
the documentation linked below for details:
|
|
|
|
> http://developer.android.com/guide/topics/manifest/uses-feature-element.html
|
|
|
|
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:
|
|
|
|
> http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html
|
|
|
|
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:
|
|
|
|
> http://jet.ro/visuals/san-angeles-observation/
|
|
|
|
|
|
IV. Android-5 Stable Native APIs:
|
|
----------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that runs
|
|
on Android 2.0 system images and above.
|
|
|
|
|
|
### The OpenGL ES 2.0 Library:
|
|
|
|
The standard OpenGL ES 2.0 headers `<GLES2/gl2.h>` and `<GLES2/gl2ext.h>` 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.
|
|
|
|
If you use them, your native module should link to /system/lib/libGLESv2.so
|
|
as in:
|
|
|
|
LOCAL_LDLIBS := -lGLESv2
|
|
|
|
Not all devices support OpenGL ES 2.0, developers should thus query the
|
|
implementation's version and extension strings, and put a `<uses-feature>`
|
|
tag in their Android manifest. See Section III above for details.
|
|
|
|
Please note that EGL APIs are only available starting from API level 9.
|
|
|
|
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.
|
|
|
|
IMPORTANT NOTE:
|
|
> 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.
|
|
|
|
|
|
IV. Android-8 Stable Native APIs:
|
|
----------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that runs
|
|
on Android 2.2 system images and above.
|
|
|
|
|
|
### The 'jnigraphics' Library:
|
|
|
|
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.
|
|
|
|
To use it, include the `<android/bitmap.h>` header in your source code, and
|
|
and link to the jnigraphics library as in:
|
|
|
|
LOCAL_LDLIBS += -ljnigraphics
|
|
|
|
For details, read the source header at the following location:
|
|
|
|
platforms/android-8/arch-arm/usr/include/android/bitmap.h
|
|
|
|
Briefly, typical usage should look like:
|
|
|
|
1. Use `AndroidBitmap_getInfo()` to retrieve information about a
|
|
given bitmap handle from JNI (e.g. its width/height/pixel format)
|
|
|
|
2. Use `AndroidBitmap_lockPixels()` to lock the pixel buffer and
|
|
retrieve a pointer to it. This ensures the pixels will not move
|
|
until `AndroidBitmap_unlockPixels()` is called.
|
|
|
|
3. Modify the pixel buffer, according to its pixel format, width,
|
|
stride, etc.., in native code.
|
|
|
|
4. Call `AndroidBitmap_unlockPixels()` to unlock the buffer.
|
|
|
|
|
|
V. Android-9 Stable Native APIs:
|
|
--------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that runs
|
|
on Android > 2.3 system images and above.
|
|
|
|
### The EGL graphics library:
|
|
|
|
EGL provides a native platform interface to allocate and manage OpenGLES
|
|
surfaces. For more information about its features, please see:
|
|
|
|
> http://www.khronos.org/egl
|
|
|
|
In a nutshell, this will allow you to do the following directly from
|
|
native code:
|
|
|
|
- List supported EGL configurations
|
|
- Allocate and release OpenGLES surfaces
|
|
- Swap/Flip surfaces for display (eglSwapBuffers)
|
|
|
|
This is provided through the following headers:
|
|
|
|
<EGL/egl.h> -> Main EGL API definitions
|
|
<EGL/eglext.h> -> EGL extension-related definitions
|
|
|
|
You cal link against the system's EGL library by adding the following
|
|
to your NDK module definition:
|
|
|
|
LOCAL_LDLIBS += -lEGL
|
|
|
|
|
|
### The OpenSL ES native audio Library:
|
|
|
|
Android native audio is based on Khronos Group OpenSL ES™ 1.0.1.
|
|
|
|
The standard OpenSL ES headers `<SLES/OpenSLES.h>` and `<SLES/OpenSLES_Platform.h>`
|
|
contain the declarations needed to perform audio input and output from the
|
|
native side of Android.
|
|
|
|
NOTE: Despite the fact that the OpenSL ES 1.0.1 specification uses
|
|
`<OpenSLES.h>` to include these headers, Khronos has modified later versions of
|
|
the document to recommend `<SLES/OpenSLES.h>` instead, hence the later
|
|
approach was adopted for Android.
|
|
|
|
This API level also provides Android-specific extensions, see the content
|
|
of `<SLES/OpenSLES_Android.h>` and `<SLES/OpenSLES_AndroidConfiguration.h>` for
|
|
details.
|
|
|
|
The system library named "libOpenSLES.so" implements the public native audio
|
|
functions. Use the following to link your modules against it:
|
|
|
|
LOCAL_LDLIBS += -lOpenSLES
|
|
|
|
For more information about this topic, please read the document docs/opensles/index.html.
|
|
|
|
|
|
### The Android native application APIs:
|
|
|
|
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.
|
|
|
|
For more information about this topic, please read the dedicated
|
|
document named docs/NATIVE-ACTIVITY.html
|
|
|
|
The following headers correspond to these new native APIs (see comments
|
|
inside them for more details):
|
|
|
|
* `<android/native_activity.h>`
|
|
> Activity lifecycle management (and general entry point)
|
|
|
|
* `<android/looper.h>`<br>
|
|
`<android/input.h>`<br>
|
|
`<android/keycodes.h>`<br>
|
|
`<android/sensor.h>`
|
|
> To Listen to input events and sensors directly from native code.
|
|
|
|
* `<android/rect.h>`<br>
|
|
`<android/window.h>`<br>
|
|
`<android/native_window.h>`<br>
|
|
`<android/native_window_jni.h>`
|
|
> Window management, including the ability to lock/unlock the pixel
|
|
buffer to draw directly into it.
|
|
|
|
* `<android/configuration.h>`<br>
|
|
`<android/asset_manager.h>`<br>
|
|
`<android/storage_manager.h>`<br>
|
|
`<android/obb.h>`
|
|
> 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).
|
|
|
|
All the corresponding functions are provided by the "libandroid.so" library
|
|
version that comes with API level 9. To use it, use the following:
|
|
|
|
LOCAL_LDLIBS += -landroid
|
|
|
|
|
|
VI. Android-14 Stable Native APIs:
|
|
----------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that runs
|
|
on Android > 4.0 system images and above.
|
|
|
|
### The OpenMAX AL native multimedia library:
|
|
|
|
Android native multimedia is based on Khronos Group OpenMAX AL™ 1.0.1.
|
|
|
|
The standard OpenMAX AL headers `<OMXAL/OpenMAXAL.h>` and `<OMXAL/OpenMAXAL_Platform.h>`
|
|
contain the declarations needed to perform multimedia output from the
|
|
native side of Android.
|
|
|
|
NOTE: Despite the fact that the OpenMAX AL 1.0.1 specification uses
|
|
`<OpenMAXAL.h>` to include these headers, Khronos has modified later versions of
|
|
the document to recommend `<OMXAL/OpenMAXAL.h>` instead, hence the later
|
|
approach was adopted for Android.
|
|
|
|
This API level also provides Android-specific extensions, see the content
|
|
of `<OMXAL/OpenMAXAL_Android.h>` for details.
|
|
|
|
The system library named "`libOpenMAXAL.so`" implements the public native multimedia
|
|
functions. Use the following to link your modules against it:
|
|
|
|
LOCAL_LDLIBS += -lOpenMAXAL
|
|
|
|
For more information about this topic, please read the document docs/openmaxal/index.html.
|
|
|
|
|
|
### The OpenSL ES native audio library:
|
|
|
|
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.
|
|
|
|
|
|
|
|
V. Android-18 Stable Native APIs:
|
|
----------------------------------
|
|
|
|
All the APIs listed below are available for developing native code that runs
|
|
on Android 4.3 system images and above.
|
|
|
|
|
|
### The OpenGL ES 3.0 Library:
|
|
|
|
The standard OpenGL ES 3.0 headers `<GLES3/gl3.h>` and `<GLES3/gl3ext.h>` contain the
|
|
declarations needed to perform OpenGL ES 3.0 rendering calls from native code.
|
|
|
|
If you use them, your native module should link to /system/lib/libGLESv3.so
|
|
as in:
|
|
|
|
LOCAL_LDLIBS := -lGLESv3
|
|
|
|
Not all devices support OpenGL ES 3.0, developers should thus query the
|
|
implementation's version and extension strings, and put a `<uses-feature>`
|
|
tag in their Android manifest. See Section III above for details.
|
|
|
|
The "gles3jni" sample application demonstrate this.
|
|
|
|
IMPORTANT NOTE:
|
|
> 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.
|
|
|