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