1page.title=Android NDK Native APIs 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>On this page</h2> 7 8 <ol> 9 <li><a href="#purpose">Overview</a></li> 10 <li><a href="#mnu">Major Native API Updates</a><li> 11 <ol> 12 <li><a href="#a3">Android API level 3</a></li> 13 <li><a href="#a4">Android API level 4</a></li> 14 <li><a href="#a5">Android API level 5</a></li> 15 <li><a href="#a8">Android API level 8</a></li> 16 <li><a href="#a9">Android API level 9</a></li> 17 <li><a href="#a14">Android API level 14</a></li> 18 <li><a href="#a18">Android API level 18</a></li> 19 </ol> 20 </ol> 21 </div> 22 </div> 23 24<p>The Android NDK provides a set of native headers and shared library files that has gradually 25increased with successive releases of new Android API levels. This page explains these headers and 26files, and maps them to specific 27<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels"> Android API levels</a>. 28</p> 29 30<h2 id="purpose">Overview</h2> 31<p>There are two basic steps to enable your app to use the libraries that the NDK provides: 32</p> 33 34<ol type ="1"> 35<li>Include in your code the headers associated with the libraries you wish to use.</li> 36 37<li>Tell the build system that your native module needs to link against the libraries at load time. 38For example, to link against {@code /system/lib/libfoo.so}, add the following line to your 39<a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a> file:</li> 40 41<pre> 42LOCAL_LDLIBS := -lfoo 43</pre> 44 45<p>To list multiple libraries, use a space as a delimiter. For more information about using the 46{@code LOCAL_LDLIBS} variable, see <a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>. 47</p> 48 49</ol> 50 51<p>For all API levels, the build system automatically links the standard C libraries, the 52standard C++ libraries, real-time extensions, and {@code pthread}; you do not need 53to include them when defining your {@code LOCAL_LDLIBS} variable. For more information about 54the C and C++ libraries, see <a href="#a3">Android API level 3</a>.</p> 55 56<p>The NDK often provides new headers and libraries for new Android releases. These files reside 57under {@code $NDK/platforms/android-<level>/<abi>/usr/include}. When the NDK does not 58have a specific new group of headers and libraries for an Android API level, it means that 59an app targeting that level should use the most recently released NDK assets. For example, 60there was no new release of NDK headers or libraries for Android API levels 6 and 7. Therefore, 61when developing an app targeting Android API level 7, you should use the headers and libraries 62located under {@code android-5/}.</p> 63 64<p>Table 1 shows the correspondence between NDK-supported API levels and Android releases.</p> 65 66<p class="table-caption" id="table1"> 67 <strong>Table 1.</strong> NDK-supported API levels and corresponding Android releases.</p> 68<table> 69 <tr> 70 <th scope="col">NDK-supported API level</th> 71 <th scope="col">Android release</th> 72 </tr> 73 <tr> 74 <td>3</td> 75 <td>1.5</td> 76 </tr> 77 <tr> 78 <td>4</td> 79 <td>1.6</td> 80 </tr> 81 <tr> 82 <td>5</td> 83 <td>2.0</td> 84 </tr> 85 <tr> 86 <td>8</td> 87 <td>2.2</td> 88 </tr> 89 <tr> 90 <td>9</td> 91 <td>2.3 through 3.0.x</td> 92 </tr> 93 <tr> 94 <td>12</td> 95 <td>3.1.x</td> 96 </tr> 97 <tr> 98 <td>13</td> 99 <td>3.2</td> 100 </tr> 101 <tr> 102 <td>14</td> 103 <td>4.0 through 4.0.2</td> 104 </tr> 105 <tr> 106 <td>15</td> 107 <td>4.0.3 and 4.0.4</td> 108 </tr> 109 <tr> 110 <td>16</td> 111 <td>4.1 and 4.1.1</td> 112 </tr> 113 <tr> 114 <td>17</td> 115 <td>4.2 and 4.2.2</td> 116 </tr> 117 <tr> 118 <td>18</td> 119 <td>4.3</td> 120 </tr> 121 <tr> 122 <td>19</td> 123 <td>4.4</td> 124 </tr> 125 <tr> 126 <td>21</td> 127 <td>4.4W and 5.0</td> 128</table> 129 130<p>Each new release of NDK headers and libraries for a given Android API level is cumulative; you 131are nearly always safe if you use the most recently released headers when building your app. For 132example, you can use the NDK headers for Android API level 21 for an app targeting API level 16. By doing so, however, you increase your APK's footprint.</p> 133 134<p> 135For more information about Android API levels, see 136<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API Level?</a>. 137</p> 138 139<h2 id="mnu">Major Native API Updates</h2> 140 141<h3 id="a3">Android API level 3</h3> 142<p>The NDK provides the following APIs for developing native code that runs on Android 1.5 system 143images and above.</p> 144 145<h4>C library</h4> 146<p>The C library headers for Android 1.5 are available through their standard names, such as 147{@code stdlib.h} and {@code stdio.h}. If a header is missing at build time, it's because the 148header is not available on the 1.5 system image.</p> 149 150<h4>C++ library</h4> 151<p>An <em>extremely</em> minimal C++ support API is available. For more 152information on C++ library support, see 153<a href="{@docRoot}ndk/guides/cpp-support.html">C++ Library Support</a>.</p> 154 155<h4>Android-specific log support</h4> 156 157<p>{@code <android/log.h>} contains various definitions that an app can use to send log 158messages to the kernel from native code. For more information about these definitions, see the 159comments in {@code $NDK/platforms/android-3/arch-arm/usr/include/android/log.h}, where {@code $NDK} 160is the root of your NDK installation.</p> 161 162<p>You can write your own wrapper macros to access this functionality. If you wish to perform 163logging, your native module should link to {@code /system/lib/liblog.so}. Implement this 164linking by including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> 165{@code Android.mk}</a> file:</p> 166 167<pre> 168LOCAL_LDLIBS := -llog 169</pre> 170 171<h4>ZLib compression library</h4> 172<p>You can use the <a href="http://www.zlib.net/manual.html">Zlib compression library</a> 173by including {@code zlib.h} and {@code zconf.h}. You must also link your native 174module against {@code /system/lib/libz.so} by including the following line in your 175<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> 176 177<pre> 178LOCAL_LDLIBS := -lz 179</pre> 180 181<h4>Dynamic linker library</h4> 182<p>You can access the Android dynamic linker's {@code dlopen()}, {@code dlsym()}, and 183{@code dlclose()} functions by including {@code dlfcn.h}. You must also link against 184{@code /system/lib/libdl.so} by including the following line in your 185<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> 186 187<pre> 188LOCAL_LDLIBS := -ldl 189</pre> 190 191<h3 id="a4">Android API level 4</h3> 192<p>The NDK provides the following APIs for developing native code that runs on Android 1.6 system 193images and above.</p> 194 195<h4>OpenGL ES 1.x Library</h4> 196<p>The standard OpenGL ES headers {@code gl.h} and {@code glext.h} contain 197the declarations necessary for performing OpenGL ES 1.x rendering calls from native code.</p> 198 199<p>To use these headers, link your native module to {@code /system/lib/libGLESv1_CM.so} by 200including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> 201{@code Android.mk}</a> file:</p> 202</p> 203 204<pre> 205LOCAL_LDLIBS := -lGLESv1_CM 206</pre> 207<p>All Android-based devices support OpenGL ES 1.0, because Android provides an Open GL 1.0-capable 208software renderer that can be used on devices without GPUs.</p> 209<p>Only Android devices that have the necessary GPU fully support OpenGL ES 1.1. An app can 210query the OpenGL ES version string and extension string to determine whether the current device 211supports the features it needs. For information on how to perform this query, see the description of 212<a href="http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml">{@code glGetString()}</a> 213in the OpenGL specification.</p> 214 215<p>Additionally, you must put a 216<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code 217<uses-feature>}</a> tag in your manifest file to indicate the version of 218<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a> 219that your application requires.</p> 220 221<p>The <a href="#egl">EGL APIs</a> are only available starting from API level 9. You can, however, 222use the VM to perform some of the operations that you would get from those APIS. These operations 223include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see 224<a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html"> 225Introducing GLSurfaceView</a>.</p> 226 227<p>The san-angeles sample application provides an example of how to perform these operations, 228rendering each frame in native code. This sample is a small Android port of the excellent 229<a href="http://jet.ro/visuals/san-angeles-observation/">San Angeles Observation</a> demo 230program.</p> 231 232<h3 id="a5">Android API level 5</h3> 233<p>The NDK provides the following APIs for developing native code that runs on Android 2.0 system 234images and above.</p> 235 236<h4>OpenGL ES 2.0 library:</h4> 237<p>The standard OpenGL ES 2.0 headers {@code <GLES2/gl2.h>} and {@code <GLES2/gl2ext.h>} 238contain the declarations needed for performing OpenGL ES 2.0 rendering calls from native code. 239These rendering calls provide the ability to use the GLSL language to define and use vertex and 240fragment shaders.</p> 241 242<p>To use OpenGL ES 2.0, link your native module to {@code /system/lib/libGLESv2.so} by 243including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> 244{@code Android.mk}</a> file:</p> 245 246<pre> 247LOCAL_LDLIBS := -lGLESv2 248</pre> 249 250<p>Not all devices support OpenGL ES 2.0. An app can query the OpenGL 251ES version string and extension string to determine whether the current device 252supports the features it needs. For information on how to perform this query, see the description of 253<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml"> 254{@code glGetString()}</a> in the OpenGL specification.</p> 255 256<p>Additionally, you must put a 257<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code 258<uses-feature>}</a> tag in your manifest file to indicate which version of OpenGL ES your 259application requires. For more information about the OpenGL ES settings for 260{@code <uses-feature>}, see 261<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p> 262 263<p>The hello-gl2 sample application provies a basic example of how to use OpenGL ES 2.0 with the 264NDK.</p> 265 266<p>The <a href="#egl">EGL APIs</a> are only available starting from API level 9. You can, however, 267use the VM to perform some of the operations that you would get from those APIs. These operations 268include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see 269<a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html"> 270Introducing GLSurfaceView</a>.</p> 271 272<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 2.0 hardware 273emulation. Running and testing code that uses this API requires a real device with hardware that can 274support OpenGL ES 2.0.</p> 275 276<h3 id="a8">Android API level 8</h3> 277<p>The NDK provides the following APIs for developing native code that runs on Android 2.2 system 278images and above.</p> 279 280<h4>jnigraphics</h4> 281<p>The {@code jnigraphics} library exposes a C-based interface that allows native code to reliably access 282the pixel buffers of Java bitmap objects. The workflow for using {@code jnigraphics} is as follows: 283</p> 284 285<ol type="1"> 286<li>Use {@code AndroidBitmap_getInfo()} to retrieve information from JNI, such as width and height, 287about a given bitmap handle.</li> 288 289<li>Use {@code AndroidBitmap_lockPixels()} to lock the pixel buffer and retrieve a pointer to it. 290Doing so ensures that the pixels do not move until the app calls 291{@code AndroidBitmap_unlockPixels()}.</li> 292 293<li>In native code, modify the pixel buffer as appropriate for its pixel format, width, and other 294characteristics.</li> 295 296<li>Call {@code AndroidBitmap_unlockPixels()} to unlock the buffer.</li> 297</ol> 298 299<p>To use {@code jnigraphics}, include the {@code <bitmap.h>} header in your source code, and 300link against {@code jnigraphics} by including the following line in your 301<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> 302 303<pre> 304LOCAL_LDLIBS += -ljnigraphics 305</pre> 306 307<p>Additional details about this feature are in the comments of the {@code bitmap.h} file. 308 309<h3 id="a9">Android API level 9</h3> 310<p>The NDK provides the following APIs for developing native code that runs on Android 2.3 system 311images and above.</p> 312 313<h4 id="egl"> EGL</h4> 314<p>EGL provides a native platform interface for allocating and managing OpenGLES surfaces. 315For more information about its features, see <a href="http://www.khronos.org/egl"> 316EGL Native Platform Interface</a>.</p> 317 318<p>EGL allows you to perform the following operations from native code:</p> 319 320<ul> 321<li>List supported EGL configurations.</li> 322<li>Allocate and release OpenGLES surfaces.</li> 323<li>Swap or flip surfaces.</li> 324</ul> 325 326<p>The following headers provide EGL functionality:</p> 327<ul> 328 <li>{@code EGL/egl.h}: the main EGL API definitions.</li> 329 <li>{@code EGL/eglext.h}: EGL extension-related definitions.</li> 330</ul> 331 332<p>To link against the system's EGL library, add the following line to your 333<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file:</p> 334 335<pre> 336LOCAL_LDLIBS += -lEGL 337</pre> 338 339<h4 id="osl">OpenSL ES</h4> 340<p>Android native audio handling is based on the Khronos Group OpenSL ES 1.0.1 API.</p> 341 342<p>The standard OpenSL ES headers {@code OpenSLES.h} and {@code OpenSLES_Platform.h} contain 343the declarations necessary for performing audio input and output from the native side of Android. 344The NDK distribution of the OpenSL ES also provides Android-specific extensions. For information 345about these extensions, see the comments in {@code OpenSLES_Android.h} and 346{@code OpenSLES_AndroidConfiguration.h}.</p> 347 348 349<p>The system library {@code libOpenSLES.so} implements the public native audio functions. Link 350against it by adding the following line to your <a href="{@docRoot}ndk/guides/android_mk.html"> 351{@code Android.mk}</a> file:</p> 352 353<pre> 354LOCAL_LDLIBS += -lOpenSLES 355</pre> 356 357<p>For more information about the OpenSL ES API, refer to 358{@code $NDK/docs/Additional_library_docs/opensles/index.html}, where {@code $NDK} is your NDK 359installation root directory.</p> 360 361<h4>Android native application APIs</h4> 362<p>Starting from API level 9, you can write an entire Android app with native code, without using 363any Java.</p> 364 365<p class="note"><strong>Note: </strong>Writing your app in native code is not, in itself, enough 366for your app to run in the VM. Moreover, your app must still access most features of the Android 367platform via JNI.</p> 368 369<p>This release provides the following native headers:</p> 370<ul> 371<li>{@code <native_activity.h>}</li> 372<li>{@code <looper.h>}</li> 373<li>{@code <input.h>}</li> 374<li>{@code <keycodes.h>}</li> 375<li>{@code <sensor.h>}</li> 376<li>{@code <rect.h>}</li> 377<li>{@code <window.h>}</li> 378<li>{@code <native_window.h>}</li> 379<li>{@code <native_window_jni.h>}</li> 380<li>{@code <configuration.h>}</li> 381<li>{@code <asset_manager.h>}</li> 382<li>{@code <storage_manager.h>}</li> 383<li>{@code <obb.h>}</li> 384</ul> 385 386<p>For more information about these headers, see the 387<a href="{@docRoot}ndk/reference/index.html">NDK API Reference documentation</a>, as well as 388the comments in the headers, themselves. Also, for more information about the larger topic of 389writing native apps, see <a href="{@docRoot}ndk/guides/concepts.html#naa"> 390Native Activities and Applications</a>. 391 392<p>When you include one or more of these headers, you must also link against the 393{@code libandroid.so} library. To link against {@code libandroid.so}, include the following line in 394your <a href="{@docRoot}ndk/guides/android_mk.html"> {@code Android.mk}</a> file:</p> 395 396<pre> 397LOCAL_LDLIBS += -landroid 398</pre> 399 400<h3 id="a14">Android API level 14</h3> 401<p>The NDK provides the following APIs for developing native code that runs on Android 4.0 system 402images and above.</p> 403 404<h4>OpenMAX AL</h4> 405<p>Android native multimedia handling is based on Khronos Group OpenMAX AL 1.0.1 API.</p> 406<p>The standard OpenMAX AL headers {@code <OMXAL/OpenMAXAL.h>} and 407{@code <OMXAL/OpenMAXAL_Platform.h>} contain the declarations necessary for performing 408multimedia output from the native side of Android.</p> 409 410<p>The NDK distribution of OpenMAX AL also provides Android-specific extensions. For information 411about these extensions, see the comments in {@code OpenMAXAL_Android.h}.</p> 412 413<p>The system library {@code libOpenMAXAL.so} implements the public native multimedia functions. 414To link against this library, include the following line in your 415<a href="{@docRoot}ndk/guides/android_mk.html"> {@code Android.mk}</a> file:</p> 416 417<pre class="fragment"> LOCAL_LDLIBS += -lOpenMAXAL 418</pre><p>For more information about this topic, see {@code $NDK/docs/openmaxal/index.html}, 419where {@code $NDK} is the root directory of your NDK installation.</p> 420 421<h4>OpenSL ES</h4> 422<p>OpenSL ES support for this Android API level adds PCM support. For more information about 423OpenSL ES support in the NDK, see <a href="#osl">OpenSL ES</a>.</p> 424 425<h3 id="a18">Android API level 18</h3> 426<p>The NDK provides the following APIs for developing native code that runs on Android 4.3 system 427images and above.</p> 428 429<h4>OpenGL ES 3.0</h4> 430 431<p>The standard OpenGL ES 3.0 headers {@code gl3.h} and {@code gl3ext.h} contain the declarations 432needed for performing OpenGL ES 3.0 rendering calls from native code. These rendering calls provide 433the ability to use the GLSL language to define and use vertex and fragment shaders. 434 435<p>To use OpenGL ES 3.0, link your native module against {@code /system/lib/libGLESv3.so} by 436including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> 437{@code Android.mk}</a> file:</p> 438 439<pre> 440LOCAL_LDLIBS := -lGLESv3 441</pre> 442 443<p>Not all devices support OpenGL ES 3.0. An app can query the OpenGL 444ES version string and extension string to determine whether the current device 445supports the features it needs. For information on how to perform this query, see the description of 446<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml"> 447{@code glGetString()}</a> in the OpenGL specification.</p> 448 449<p>Additionally, you must put a 450<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code 451<uses-feature>}</a> tag in your manifest file to indicate which version of OpenGL ES your 452application requires. For more information about the OpenGL ES settings for 453{@code <uses-feature>}, see 454<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p> 455 456<p>The gles3jni sample application provides a basic example of how to use OpenGL ES 3.0 with the 457NDK.</p> 458 459<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 3.0 hardware 460emulation. Running and testing code that uses this API requires a real device with hardware that can 461support OpenGL ES 3.0.</p> 462 463 464<h3 id="a18">Android API level 21</h3> 465<p>The NDK provides the following APIs for developing native code that runs on Android 4.3 system 466images and above.</p> 467 468<h4>OpenGL ES 3.1</h4> 469 470<p>The standard OpenGL ES 3.1 headers {@code gl31.h} and {@code gl3ext.h} contain the declarations 471needed for performing OpenGL ES 3.1 rendering calls from native code. These rendering calls provide 472the ability to use the GLSL language to define and use vertex and fragment shaders. 473 474<p>To use OpenGL ES 3.1, link your native module against {@code /system/lib/libGLESv3.so} by 475including the following line in your <a href="{@docRoot}ndk/guides/android_mk.html"> 476{@code Android.mk}</a> file:</p> 477 478<pre> 479LOCAL_LDLIBS := -lGLESv3 480</pre> 481 482<p>Not all devices support OpenGL ES 3.1. An app can query the OpenGL 483ES version string and extension string to determine whether the current device 484supports the features it needs. For information on how to perform this query, see the description of 485<a href="https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGetString.xml"> 486{@code glGetString()}</a> in the OpenGL specification.</p> 487 488<p>Additionally, you must put a 489<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">{@code 490<uses-feature>}</a> tag in your manifest file to indicate which version of OpenGL ES your 491application requires. For more information about the OpenGL ES settings for 492{@code <uses-feature>}, see 493<a href="http://developer.android.com/guide/topics/graphics/opengl.html#manifest">OpenGL ES</a>.</p> 494 495<p>The gles3jni sample application provides a basic example of how to use OpenGL ES 3.1 with the 496NDK.</p> 497 498<p class="note"><strong>Note:</strong> The Android emulator does not support OpenGL ES 3.1 hardware 499emulation. Running and testing code that uses this API requires a real device with hardware that can 500support OpenGL ES 3.1.</p> 501 502