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

Note that android-6 and android-7 are the same than android-5 for the NDK,
i.e. they provide exactly the same native ABIs!

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 (build/platforms/android-3/common/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.so


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, at the moment, native headers and libraries for the EGL APIs
are *not* available. EGL is used to perform surface creation and flipping
(instead of rendering). The corresponding operations must be performed in your
VM application instead, 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.so

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, at the moment, native headers and libraries for the EGL APIs
are *not* available. EGL is used to perform surface creation and flipping
(instead of rendering). The corresponding operations must be performed in your
VM application instead, for example with a GLSurfaceView, as described here:

http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html

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:

    build/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.