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. 233 234 235 IV. Android-8 Stable Native APIs: 236 ---------------------------------- 237 238 All the APIs listed below are available for developing native code that runs 239 on Android 2.2 system images and above. 240 241 242 The 'jnigraphics' Library: 243 -------------------------- 244 245 This is a tiny library that exposes a stable, C-based, interface that allows 246 native code to reliably access the pixel buffers of Java bitmap objects. 247 248 To use it, include the <android/bitmap.h> header in your source code, and 249 and link to the jnigraphics library as in: 250 251 LOCAL_LDLIBS += -ljnigraphics 252 253 For details, read the source header at the following location: 254 255 build/platforms/android-8/arch-arm/usr/include/android/bitmap.h 256 257 Briefly, 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
