docs/STABLE-APIS.TXT

   1 Android NDK Stable APIs:
   2 ========================
   3
   4 This is the list of stable APIs/ABIs exposed by the Android NDK.
   5
   6 I. Purpose:
   7 -----------
   8
   9 Each API corresponds to a set of headers files, and a shared library file
  10 that contains the corresponding implementation, and which must be linked
  11 against by your native code.
  12
  13 For example, to use system library "Foo", you would include a header
  14 like <foo.h> in your code, then tell the build system that your native
  15 module needs to link to /system/lib/libfoo.so at load-time by adding
  16 the following line to your Android.mk file:
  17
  18   LOCAL_LDLIBS := -lfoo
  19
  20 Note that the build system automatically links the C library, the Math
  21 library and the C++ support library to your native code, there is no
  22 need to list them in a LOCAL_LDLIBS line.
  23
  24 There are several "API Levels" defined. Each API level corresponds to
  25 a given Android system platform release. The following levels are
  26 currently supported:
  27
  28     android-3      -> Official Android 1.5 system images
  29     android-4      -> Official Android 1.6 system images
  30     android-5      -> Official Android 2.0 system images
  31     android-6      -> Official Android 2.0.1 system images
  32     android-7      -> Official Android 2.1 system images
  33     android-8      -> Official Android 2.2 system images
  34
  35 Note that android-6 and android-7 are the same than android-5 for the NDK,
  36 i.e. they provide exactly the same native ABIs!
  37
  38 II. Android-3 Stable Native APIs:
  39 ---------------------------------
  40
  41 All the APIs listed below are available for developing native code that
  42 runs on Android 1.5 system images and above.
  43
  44 The C Library:
  45 --------------
  46
  47 The C library headers, as they are defined on Android 1.5 are available
  48 through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header
  49 is not there at build time, it's because its implementation is not available
  50 on a 1.5 system image.
  51
  52 The build system automatically links your native modules to the C library,
  53 you don't need to add it to LOCAL_LDLIBS.
  54
  55 Note that the Android C library includes support for pthread (<pthread.h>),
  56 so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time
  57 extensions (-lrt on typical Linux distributions).
  58
  59
  60 ** VERY IMPORTANT NOTE: ******************************************************
  61 *
  62 *  The kernel-specific headers in <linux/...> and <asm/...> are not considered
  63 *  stable at this point. Avoid including them directly because some of them
  64 *  are likely to change in future releases of the platform. This is especially
  65 *  true for anything related to specific hardware definitions.
  66 *
  67 ******************************************************************************
  68
  69
  70 The Math Library:
  71 -----------------
  72
  73 <math.h> is available, and the math library is automatically linked to your
  74 native modules at build time, so there is no need to list "-lm" through
  75 LOCAL_LDLIBS.
  76
  77
  78
  79 C++ Library:
  80 ------------
  81
  82 An *extremely* minimal C++ support API is available. For Android 1.5, this is
  83 currently limited to the following headers:
  84
  85    <cstddef>
  86    <new>
  87    <utility>
  88    <stl_pair.h>
  89
  90 They may not contain all definitions required by the standard. Notably,
  91 support for C++ exceptions and RTTI is not available with Android 1.5 system
  92 images.
  93
  94 The C++ support library (-lstdc++) is automatically linked to your native
  95 modules too, so there is no need to list it through LOCAL_LDLIBS
  96
  97
  98
  99 Android-specific Log Support:
 100 -----------------------------
 101
 102 <android/log.h> contains various definitions that can be used to send log
 103 messages to the kernel from your native code. Please have a look at its
 104 content in (build/platforms/android-3/common/include/android/log.h), which
 105 contain many informative comments on how to use it.
 106
 107 You should be able to write helpful wrapper macros for your own usage to
 108 access this facility.
 109
 110 If you use it, your native module should link to /system/lib/liblog.so with:
 111
 112   LOCAL_LDLIBS := -llog
 113
 114
 115 ZLib Compression Library:
 116 -------------------------
 117
 118 <zlib.h> and <zconf.h> are available and can be used to use the ZLib
 119 compression library. Documentation for it is at the ZLib page:
 120
 121     http://www.zlib.net/manual.html
 122
 123 If you use it, your native module should link to /system/lib/libz.so with:
 124
 125   LOCAL_LDLIBS := -lz
 126
 127
 128 Dynamic Linker Library:
 129 -----------------------
 130
 131 <dlfcn.h> is available and can be used to use the dlopen()/dlsym()/dlclose()
 132 functions provided by the Android dynamic linker. You will need to link
 133 against /system/lib/libdl.so with:
 134
 135   LOCAL_LDLIBS := -ldl
 136
 137
 138 III. Android-4 Stable Native APIs:
 139 ----------------------------------
 140
 141 All the APIs listed below are available for developing native code that runs
 142 on Android 1.6 system images and above,
 143
 144
 145 The OpenGL ES 1.x Library:
 146 --------------------------
 147
 148 The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the
 149 declarations needed to perform OpenGL ES 1.x rendering calls from native
 150 code.
 151
 152 If you use them, your native module should link to /system/lib/libGLESv1_CM.so
 153 as in:
 154
 155   LOCAL_LDLIBS := -lGLESv1_CM.so
 156
 157
 158 The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs.
 159 Please note that:
 160
 161   - OpenGL ES 1.0 is supported on *all* Android-based devices.
 162   - OpenGL ES 1.1 is fully supported only on specific devices that
 163     have the corresponding GPU.
 164
 165 This is because Android comes with a 1.0-capable software renderer that can
 166 be used on GPU-less devices.
 167
 168 Developers should query the OpenGL ES version string and extension string
 169 to know if the current device supports the features they need. See the
 170 description of glGetString() in the specification to see how to do that:
 171
 172     http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml
 173
 174 Additionally, developers must put a <uses-feature> tag in their manifest
 175 file to indicate which version of OpenGL ES their application requires. See
 176 the documentation linked below for details:
 177
 178  http://developer.android.com/guide/topics/manifest/uses-feature-element.html
 179
 180 Please note that, at the moment, native headers and libraries for the EGL APIs
 181 are *not* available. EGL is used to perform surface creation and flipping
 182 (instead of rendering). The corresponding operations must be performed in your
 183 VM application instead, for example with a GLSurfaceView, as described here:
 184
 185 http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html
 186
 187 The "san-angeles" sample application shows how you can do that, while
 188 rendering each frame in native code. This is a small Android port of the
 189 excellent "San Angeles Observation" demo program. For more information about
 190 it, see:
 191
 192     http://jet.ro/visuals/san-angeles-observation/
 193
 194
 195 IV. Android-5 Stable Native APIs:
 196 ----------------------------------
 197
 198 All the APIs listed below are available for developing native code that runs
 199 on Android 2.0 system images and above.
 200
 201
 202 The OpenGL ES 2.0 Library:
 203 --------------------------
 204
 205 The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the
 206 declarations needed to perform OpenGL ES 2.0 rendering calls from native code.
 207 This includes the ability to define and use vertex and fragment shaders using the
 208 GLSL language.
 209
 210 If you use them, your native module should link to /system/lib/libGLESv2.so
 211 as in:
 212
 213   LOCAL_LDLIBS := -lGLESv2.so
 214
 215 Not all devices support OpenGL ES 2.0, developers should thus query the
 216 implementation's version and extension strings, and put a <uses-feature>
 217 tag in their Android manifest. See Section III above for details.
 218
 219 Please note that, at the moment, native headers and libraries for the EGL APIs
 220 are *not* available. EGL is used to perform surface creation and flipping
 221 (instead of rendering). The corresponding operations must be performed in your
 222 VM application instead, for example with a GLSurfaceView, as described here:
 223
 224 http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html
 225
 226 The "hello-gl2" sample application demonstrate this. It is used to draw a very
 227 simple triangle with the help of a vertex and fragment shaders.
 228
 229 IMPORTANT NOTE:
 230     The Android emulator does not support OpenGL ES 2.0 hardware emulation
 231     at this time. Running and testing code that uses this API requires a
 232     real device with such capabilities.