1Android NDK Stable APIs: 2======================== 3 4This is the list of stable APIs/ABIs exposed by the Android NDK. 5 6I. Purpose: 7----------- 8 9Each API corresponds to a set of headers files, and a shared library file 10that contains the corresponding implementation, and which must be linked 11against by your native code. 12 13For example, to use system library "Foo", you would include a header 14like <foo.h> in your code, then tell the build system that your native 15module needs to link to /system/lib/libfoo.so at load-time by adding 16the following line to your Android.mk file: 17 18 LOCAL_LDLIBS := -lfoo 19 20Note that the build system automatically links the C library, the Math 21library and the C++ support library to your native code, there is no 22need to list them in a LOCAL_LDLIBS line. 23 24There are several "API Levels" defined. Each API level corresponds to 25a given Android system platform release. The following levels are 26currently 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 35Note that android-6 and android-7 are the same than android-5 for the NDK, 36i.e. they provide exactly the same native ABIs! 37 38II. Android-3 Stable Native APIs: 39--------------------------------- 40 41All the APIs listed below are available for developing native code that 42runs on Android 1.5 system images and above. 43 44The C Library: 45-------------- 46 47The C library headers, as they are defined on Android 1.5 are available 48through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header 49is not there at build time, it's because its implementation is not available 50on a 1.5 system image. 51 52The build system automatically links your native modules to the C library, 53you don't need to add it to LOCAL_LDLIBS. 54 55Note that the Android C library includes support for pthread (<pthread.h>), 56so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time 57extensions (-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 70The Math Library: 71----------------- 72 73<math.h> is available, and the math library is automatically linked to your 74native modules at build time, so there is no need to list "-lm" through 75LOCAL_LDLIBS. 76 77 78 79C++ Library: 80------------ 81 82An *extremely* minimal C++ support API is available. For Android 1.5, this is 83currently limited to the following headers: 84 85 <cstddef> 86 <new> 87 <utility> 88 <stl_pair.h> 89 90They may not contain all definitions required by the standard. Notably, 91support for C++ exceptions and RTTI is not available with Android 1.5 system 92images. 93 94The C++ support library (-lstdc++) is automatically linked to your native 95modules too, so there is no need to list it through LOCAL_LDLIBS 96 97 98 99Android-specific Log Support: 100----------------------------- 101 102<android/log.h> contains various definitions that can be used to send log 103messages to the kernel from your native code. Please have a look at its 104content in (build/platforms/android-3/common/include/android/log.h), which 105contain many informative comments on how to use it. 106 107You should be able to write helpful wrapper macros for your own usage to 108access this facility. 109 110If you use it, your native module should link to /system/lib/liblog.so with: 111 112 LOCAL_LDLIBS := -llog 113 114 115ZLib Compression Library: 116------------------------- 117 118<zlib.h> and <zconf.h> are available and can be used to use the ZLib 119compression library. Documentation for it is at the ZLib page: 120 121 http://www.zlib.net/manual.html 122 123If you use it, your native module should link to /system/lib/libz.so with: 124 125 LOCAL_LDLIBS := -lz 126 127 128Dynamic Linker Library: 129----------------------- 130 131<dlfcn.h> is available and can be used to use the dlopen()/dlsym()/dlclose() 132functions provided by the Android dynamic linker. You will need to link 133against /system/lib/libdl.so with: 134 135 LOCAL_LDLIBS := -ldl 136 137 138III. Android-4 Stable Native APIs: 139---------------------------------- 140 141All the APIs listed below are available for developing native code that runs 142on Android 1.6 system images and above, 143 144 145The OpenGL ES 1.x Library: 146-------------------------- 147 148The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the 149declarations needed to perform OpenGL ES 1.x rendering calls from native 150code. 151 152If you use them, your native module should link to /system/lib/libGLESv1_CM.so 153as in: 154 155 LOCAL_LDLIBS := -lGLESv1_CM.so 156 157 158The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs. 159Please 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 165This is because Android comes with a 1.0-capable software renderer that can 166be used on GPU-less devices. 167 168Developers should query the OpenGL ES version string and extension string 169to know if the current device supports the features they need. See the 170description 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 174Additionally, developers must put a <uses-feature> tag in their manifest 175file to indicate which version of OpenGL ES their application requires. See 176the documentation linked below for details: 177 178 http://developer.android.com/guide/topics/manifest/uses-feature-element.html 179 180Please note that, at the moment, native headers and libraries for the EGL APIs 181are *not* available. EGL is used to perform surface creation and flipping 182(instead of rendering). The corresponding operations must be performed in your 183VM application instead, for example with a GLSurfaceView, as described here: 184 185http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html 186 187The "san-angeles" sample application shows how you can do that, while 188rendering each frame in native code. This is a small Android port of the 189excellent "San Angeles Observation" demo program. For more information about 190it, see: 191 192 http://jet.ro/visuals/san-angeles-observation/ 193 194 195IV. Android-5 Stable Native APIs: 196---------------------------------- 197 198All the APIs listed below are available for developing native code that runs 199on Android 2.0 system images and above. 200 201 202The OpenGL ES 2.0 Library: 203-------------------------- 204 205The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the 206declarations needed to perform OpenGL ES 2.0 rendering calls from native code. 207This includes the ability to define and use vertex and fragment shaders using the 208GLSL language. 209 210If you use them, your native module should link to /system/lib/libGLESv2.so 211as in: 212 213 LOCAL_LDLIBS := -lGLESv2.so 214 215Not all devices support OpenGL ES 2.0, developers should thus query the 216implementation's version and extension strings, and put a <uses-feature> 217tag in their Android manifest. See Section III above for details. 218 219Please note that, at the moment, native headers and libraries for the EGL APIs 220are *not* available. EGL is used to perform surface creation and flipping 221(instead of rendering). The corresponding operations must be performed in your 222VM application instead, for example with a GLSurfaceView, as described here: 223 224http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html 225 226The "hello-gl2" sample application demonstrate this. It is used to draw a very 227simple triangle with the help of a vertex and fragment shaders. 228 229IMPORTANT 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. 233 234 235IV. Android-8 Stable Native APIs: 236---------------------------------- 237 238All the APIs listed below are available for developing native code that runs 239on Android 2.2 system images and above. 240 241 242The 'jnigraphics' Library: 243-------------------------- 244 245This is a tiny library that exposes a stable, C-based, interface that allows 246native code to reliably access the pixel buffers of Java bitmap objects. 247 248To use it, include the <android/bitmap.h> header in your source code, and 249and link to the jnigraphics library as in: 250 251 LOCAL_LDLIBS += -ljnigraphics 252 253For details, read the source header at the following location: 254 255 build/platforms/android-8/arch-arm/usr/include/android/bitmap.h 256 257Briefly, typical usage should look like: 258 259 1/ Use AndroidBitmap_getInfo() to retrieve information about a 260 given bitmap handle from JNI (e.g. its width/height/pixel format) 261 262 2/ Use AndroidBitmap_lockPixels() to lock the pixel buffer and 263 retrieve a pointer to it. This ensures the pixels will not move 264 until AndroidBitmap_unlockPixels() is called. 265 266 3/ Modify the pixel buffer, according to its pixel format, width, 267 stride, etc.., in native code. 268 269 4/ Call AndroidBitmap_unlockPixels() to unlock the buffer. 270