1 <html><body><pre>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 android-9 -> Official Android 2.3 system images 35 36 Note that android-6 and android-7 are the same as android-5 for the NDK, 37 i.e. they provide exactly the same native ABIs! 38 39 IMPORTANT: 40 The headers corresponding to a given API level are now located 41 under $NDK/platforms/android-<level>/arch-arm/usr/include 42 43 44 II. Android-3 Stable Native APIs: 45 --------------------------------- 46 47 All the APIs listed below are available for developing native code that 48 runs on Android 1.5 system images and above. 49 50 The C Library: 51 -------------- 52 53 The C library headers, as they are defined on Android 1.5 are available 54 through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header 55 is not there at build time, it's because its implementation is not available 56 on a 1.5 system image. 57 58 The build system automatically links your native modules to the C library, 59 you don't need to add it to LOCAL_LDLIBS. 60 61 Note that the Android C library includes support for pthread (<pthread.h>), 62 so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time 63 extensions (-lrt on typical Linux distributions). 64 65 66 ** VERY IMPORTANT NOTE: ****************************************************** 67 * 68 * The kernel-specific headers in <linux/...> and <asm/...> are not considered 69 * stable at this point. Avoid including them directly because some of them 70 * are likely to change in future releases of the platform. This is especially 71 * true for anything related to specific hardware definitions. 72 * 73 ****************************************************************************** 74 75 76 The Math Library: 77 ----------------- 78 79 <math.h> is available, and the math library is automatically linked to your 80 native modules at build time, so there is no need to list "-lm" through 81 LOCAL_LDLIBS. 82 83 84 85 C++ Library: 86 ------------ 87 88 An *extremely* minimal C++ support API is available. For Android 1.5, this is 89 currently limited to the following headers: 90 91 <cstddef> 92 <new> 93 <utility> 94 <stl_pair.h> 95 96 They may not contain all definitions required by the standard. Notably, 97 support for C++ exceptions and RTTI is not available with Android 1.5 system 98 images. 99 100 The C++ support library (-lstdc++) is automatically linked to your native 101 modules too, so there is no need to list it through LOCAL_LDLIBS 102 103 104 105 Android-specific Log Support: 106 ----------------------------- 107 108 <android/log.h> contains various definitions that can be used to send log 109 messages to the kernel from your native code. Please have a look at its 110 content in (build/platforms/android-3/common/include/android/log.h), which 111 contain many informative comments on how to use it. 112 113 You should be able to write helpful wrapper macros for your own usage to 114 access this facility. 115 116 If you use it, your native module should link to /system/lib/liblog.so with: 117 118 LOCAL_LDLIBS := -llog 119 120 121 ZLib Compression Library: 122 ------------------------- 123 124 <zlib.h> and <zconf.h> are available and can be used to use the ZLib 125 compression library. Documentation for it is at the ZLib page: 126 127 http://www.zlib.net/manual.html 128 129 If you use it, your native module should link to /system/lib/libz.so with: 130 131 LOCAL_LDLIBS := -lz 132 133 134 Dynamic Linker Library: 135 ----------------------- 136 137 <dlfcn.h> is available and can be used to use the dlopen()/dlsym()/dlclose() 138 functions provided by the Android dynamic linker. You will need to link 139 against /system/lib/libdl.so with: 140 141 LOCAL_LDLIBS := -ldl 142 143 144 III. Android-4 Stable Native APIs: 145 ---------------------------------- 146 147 All the APIs listed below are available for developing native code that runs 148 on Android 1.6 system images and above, 149 150 151 The OpenGL ES 1.x Library: 152 -------------------------- 153 154 The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the 155 declarations needed to perform OpenGL ES 1.x rendering calls from native 156 code. 157 158 If you use them, your native module should link to /system/lib/libGLESv1_CM.so 159 as in: 160 161 LOCAL_LDLIBS := -lGLESv1_CM 162 163 164 The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs. 165 Please note that: 166 167 - OpenGL ES 1.0 is supported on *all* Android-based devices. 168 - OpenGL ES 1.1 is fully supported only on specific devices that 169 have the corresponding GPU. 170 171 This is because Android comes with a 1.0-capable software renderer that can 172 be used on GPU-less devices. 173 174 Developers should query the OpenGL ES version string and extension string 175 to know if the current device supports the features they need. See the 176 description of glGetString() in the specification to see how to do that: 177 178 http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml 179 180 Additionally, developers must put a <uses-feature> tag in their manifest 181 file to indicate which version of OpenGL ES their application requires. See 182 the documentation linked below for details: 183 184 http://developer.android.com/guide/topics/manifest/uses-feature-element.html 185 186 Please note that, at the moment, native headers and libraries for the EGL APIs 187 are *not* available. EGL is used to perform surface creation and flipping 188 (instead of rendering). The corresponding operations must be performed in your 189 VM application instead, for example with a GLSurfaceView, as described here: 190 191 http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html 192 193 The "san-angeles" sample application shows how you can do that, while 194 rendering each frame in native code. This is a small Android port of the 195 excellent "San Angeles Observation" demo program. For more information about 196 it, see: 197 198 http://jet.ro/visuals/san-angeles-observation/ 199 200 201 IV. Android-5 Stable Native APIs: 202 ---------------------------------- 203 204 All the APIs listed below are available for developing native code that runs 205 on Android 2.0 system images and above. 206 207 208 The OpenGL ES 2.0 Library: 209 -------------------------- 210 211 The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the 212 declarations needed to perform OpenGL ES 2.0 rendering calls from native code. 213 This includes the ability to define and use vertex and fragment shaders using the 214 GLSL language. 215 216 If you use them, your native module should link to /system/lib/libGLESv2.so 217 as in: 218 219 LOCAL_LDLIBS := -lGLESv2 220 221 Not all devices support OpenGL ES 2.0, developers should thus query the 222 implementation's version and extension strings, and put a <uses-feature> 223 tag in their Android manifest. See Section III above for details. 224 225 Please note that, at the moment, native headers and libraries for the EGL APIs 226 are *not* available. EGL is used to perform surface creation and flipping 227 (instead of rendering). The corresponding operations must be performed in your 228 VM application instead, for example with a GLSurfaceView, as described here: 229 230 http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html 231 232 The "hello-gl2" sample application demonstrate this. It is used to draw a very 233 simple triangle with the help of a vertex and fragment shaders. 234 235 IMPORTANT NOTE: 236 The Android emulator does not support OpenGL ES 2.0 hardware emulation 237 at this time. Running and testing code that uses this API requires a 238 real device with such capabilities. 239 240 241 IV. Android-8 Stable Native APIs: 242 ---------------------------------- 243 244 All the APIs listed below are available for developing native code that runs 245 on Android 2.2 system images and above. 246 247 248 The 'jnigraphics' Library: 249 -------------------------- 250 251 This is a tiny library that exposes a stable, C-based, interface that allows 252 native code to reliably access the pixel buffers of Java bitmap objects. 253 254 To use it, include the <android/bitmap.h> header in your source code, and 255 and link to the jnigraphics library as in: 256 257 LOCAL_LDLIBS += -ljnigraphics 258 259 For details, read the source header at the following location: 260 261 build/platforms/android-8/arch-arm/usr/include/android/bitmap.h 262 263 Briefly, typical usage should look like: 264 265 1/ Use AndroidBitmap_getInfo() to retrieve information about a 266 given bitmap handle from JNI (e.g. its width/height/pixel format) 267 268 2/ Use AndroidBitmap_lockPixels() to lock the pixel buffer and 269 retrieve a pointer to it. This ensures the pixels will not move 270 until AndroidBitmap_unlockPixels() is called. 271 272 3/ Modify the pixel buffer, according to its pixel format, width, 273 stride, etc.., in native code. 274 275 4/ Call AndroidBitmap_unlockPixels() to unlock the buffer. 276 277 278 V. Android-9 Stable Native APIs: 279 -------------------------------- 280 281 All the APIs listed below are available for developing native code that runs 282 on Android > 2.2 system images and above. 283 284 The OpenSL ES native audio Library: 285 ----------------------------------- 286 287 Android native audio is based on Khronos Group OpenSL ES™ 1.0.1. 288 289 The standard OpenSL ES headers <SLES/OpenSLES.h> and <SLES/OpenSLES_Platform.h> 290 contain the declarations needed to perform audio input and output from the 291 native side of Android. 292 293 NOTE: Despite the fact that the current OpenSL ES specification uses 294 <OpenSLES.h> to include these headers, Khronos is currently modifying 295 the document to recommend <SLES/OpenSLES.h> instead, hence the later 296 approach was adopted for Android. 297 298 This API level also provides Android-specific extensions, see the content 299 of <SLES/OpenSLES_Android.h> and <SLES/OpenSLES_AndroidConfiguration.h> for 300 details. 301 302 The system library named "libOpenSLES.so" implements the public native audio 303 functions. Use the following to link your modules against it: 304 305 LOCAL_LDLIBS += -lOpenSLES 306 307 308 The Android native application APIs: 309 ------------------------------------ 310 311 Starting from API level 9, it is possible to entirely write an Android 312 application with native code (i.e. without any Java). That does not mean 313 that your code does not run inside a VM though, and most of the features 314 of the platform will still need to be accessed through JNI. 315 316 For more information about this topic, please read the dedicated 317 document named docs/NATIVE-ACTIVITY.html (TODO: WRITE DOC). 318 319 The following headers correspond to these new native APIs (see comments 320 inside them for more details): 321 322 <android/native_activity.h> 323 324 Activity lifecycle management (and general entry point) 325 326 <android/looper.h> 327 <android/input.h> 328 <android/keycodes.h> 329 <android/sensor.h> 330 331 To Listen to input events and sensors directly from native code. 332 333 <android/rect.h> 334 <android/window.h> 335 <android/native_window.h> 336 <android/native_window_jni.h> 337 338 Window management, including the ability to lock/unlock the pixel 339 buffer to draw directly into it. 340 341 <android/configuration.h> 342 <android/asset_manager.h> 343 <android/storage_manager.h> 344 <android/obb.h> 345 Direct (read-only) access to assets embedded in your .apk. or 346 the Opaque Binary Blob (OBB) files, a new feature of Android X.X 347 that allows one to distribute large amount of application data 348 outside of the .apk (useful for game assets, for example). 349 350 All the corresponding functions are provided by the "libandroid.so" library 351 version that comes with API level 9. To use it, use the following: 352 353 LOCAL_LDLIBS += -landroid 354 </pre></body></html> 355
