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