Skip to content

Most visited

Recently visited

navigation

Android NDK Native APIs

The Android NDK provides a set of native headers and shared library files that has gradually increased with successive releases of new Android API levels. This page explains these headers and files, and maps them to specific Android API levels.

Overview

There are two basic steps to enable your app to use the libraries that the NDK provides:

  1. Include in your code the headers associated with the libraries you wish to use.
  2. Tell the build system that your native module needs to link against the libraries at load time. For example, to link against /system/lib/libfoo.so, add the following line to your Android.mk file:
  3. LOCAL_LDLIBS := -lfoo
    

    To list multiple libraries, use a space as a delimiter. For more information about using the LOCAL_LDLIBS variable, see Android.mk.

For all API levels, the build system automatically links the standard C libraries, the standard C++ libraries, real-time extensions, and pthread; you do not need to include them when defining your LOCAL_LDLIBS variable. For more information about the C and C++ libraries, see Android API level 3.

The NDK often provides new headers and libraries for new Android releases. These files reside under $NDK/platforms/android-<level>/<abi>/usr/include. When the NDK does not have a specific new group of headers and libraries for an Android API level, it means that an app targeting that level should use the most recently released NDK assets. For example, there was no new release of NDK headers or libraries for Android API levels 6 and 7. Therefore, when developing an app targeting Android API level 7, you should use the headers and libraries located under android-5/.

Table 1 shows the correspondence between NDK-supported API levels and Android releases.

Table 1. NDK-supported API levels and corresponding Android releases.

NDK-supported API level Android release
3 1.5
4 1.6
5 2.0 through 2.1.x
8 2.2
9 2.3 through 3.0.x
12 3.1.x
13 3.2
14 4.0 through 4.0.2
15 4.0.3 and 4.0.4
16 4.1 and 4.1.1
17 4.2 and 4.2.2
18 4.3
19 4.4 amd 4.4w
21 5.0 and 5.1
23 6.0
24 7.0 through 7.1.1
26 Android O Developer Preview

For more information about Android API levels, see What is API Level?.

Major Native API Updates

Android API level 3

The NDK provides the following APIs for developing native code that runs on Android 1.5 system images and above.

C library

The C library headers for Android 1.5 are available through their standard names, such as stdlib.h and stdio.h. If a header is missing at build time, it's because the header is not available on the 1.5 system image.

C++ library

An extremely minimal C++ support API is available. For more information on C++ library support, see C++ Library Support.

Android-specific log support

<android/log.h> contains various definitions that an app can use to send log messages to the kernel from native code. For more information about these definitions, see the comments in <android/log.h>.

You can write your own wrapper macros to access this functionality. If you wish to perform logging, your native module should link to /system/lib/liblog.so. Implement this linking by including the following line in your Android.mk file:

LOCAL_LDLIBS := -llog

ZLib compression library

You can use the Zlib compression library by including zlib.h and zconf.h. You must also link your native module against /system/lib/libz.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -lz

Dynamic linker library

You can access the Android dynamic linker's dlopen(), dlsym(), and dlclose() functions by including dlfcn.h. You must also link against /system/lib/libdl.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -ldl

Android API level 4

The NDK provides the following APIs for developing native code that runs on Android 1.6 system images and above.

OpenGL ES 1.x Library

The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the declarations necessary for performing OpenGL ES 1.x rendering calls from native code.

To use these headers, link your native module to /system/lib/libGLESv1_CM.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -lGLESv1_CM

All Android-based devices support OpenGL ES 1.0, because Android provides an Open GL 1.0-capable software renderer that can be used on devices without GPUs.

Only Android devices that have the necessary GPU fully support OpenGL ES 1.1. An app can query the OpenGL ES version string and extension string to determine whether the current device supports the features it needs. For information on how to perform this query, see the description of glGetString() in the OpenGL specification.

Additionally, you must put a <uses-feature> tag in your manifest file to indicate the version of OpenGL ES that your application requires.

The EGL APIs are only available starting from API level 9. You can, however, use the VM to perform some of the operations that you would get from those APIS. These operations include surface creation and flipping. For an example of how to use GLSurfaceView, see Introducing GLSurfaceView.

The san-angeles sample application provides an example of how to perform these operations, rendering each frame in native code. This sample is a small Android port of the excellent San Angeles Observation demo program.

Android API level 5

The NDK provides the following APIs for developing native code that runs on Android 2.0 system images and above.

OpenGL ES 2.0 library:

The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the declarations needed for performing OpenGL ES 2.0 rendering calls from native code. These rendering calls provide the ability to use the GLSL language to define and use vertex and fragment shaders.

To use OpenGL ES 2.0, link your native module to /system/lib/libGLESv2.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -lGLESv2

Not all devices support OpenGL ES 2.0. An app can query the OpenGL ES version string and extension string to determine whether the current device supports the features it needs. For information on how to perform this query, see the description of glGetString() in the OpenGL specification.

Additionally, you must put a <uses-feature> tag in your manifest file to indicate which version of OpenGL ES your application requires. For more information about the OpenGL ES settings for <uses-feature>, see OpenGL ES.

The hello-gl2 sample application provies a basic example of how to use OpenGL ES 2.0 with the NDK.

The EGL APIs are only available starting from API level 9. You can, however, use the VM to perform some of the operations that you would get from those APIs. These operations include surface creation and flipping. For an example of how to use GLSurfaceView, see Introducing GLSurfaceView.

Android API level 8

The NDK provides the following APIs for developing native code that runs on Android 2.2 system images and above.

jnigraphics

The jnigraphics library exposes a C-based interface that allows native code to reliably access the pixel buffers of Java bitmap objects. The workflow for using jnigraphics is as follows:

  1. Use AndroidBitmap_getInfo() to retrieve information from JNI, such as width and height, about a given bitmap handle.
  2. Use AndroidBitmap_lockPixels() to lock the pixel buffer and retrieve a pointer to it. Doing so ensures that the pixels do not move until the app calls AndroidBitmap_unlockPixels().
  3. In native code, modify the pixel buffer as appropriate for its pixel format, width, and other characteristics.
  4. Call AndroidBitmap_unlockPixels() to unlock the buffer.

To use jnigraphics, include the <bitmap.h> header in your source code, and link against jnigraphics by including the following line in your Android.mk file:

LOCAL_LDLIBS += -ljnigraphics

Additional details about this feature are in the comments of the <android/bitmap.h> file.

Android API level 9

Native API changes introduced in API level 9

  1. EGL
  2. OpenSL ES
  3. Native Application APIs

The NDK provides the following APIs for developing native code that runs on Android 2.3 system images and above.

EGL

EGL provides a native platform interface for allocating and managing OpenGLES surfaces. For more information about its features, see EGL Native Platform Interface.

EGL allows you to perform the following operations from native code:

  • List supported EGL configurations.
  • Allocate and release OpenGLES surfaces.
  • Swap or flip surfaces.

The following headers provide EGL functionality:

  • <EGL/egl.h>: the main EGL API definitions.
  • <EGL/eglext.h>: EGL extension-related definitions.

To link against the system's EGL library, add the following line to your Android.mk file:

LOCAL_LDLIBS += -lEGL

OpenSL ES

Android native audio handling is based on the Khronos Group OpenSL ES 1.0.1 API.

The standard OpenSL ES headers <SLES/OpenSLES.h> and <SLES/OpenSLES_Platform.h> contain the declarations necessary for performing audio input and output from the native side of Android. The NDK distribution of the OpenSL ES also provides Android-specific extensions. For information about these extensions, see the comments in <SLES/OpenSLES_Android.h> and <SLES/OpenSLES_AndroidConfiguration.h>.

The system library libOpenSLES.so implements the public native audio functions. Link against it by adding the following line to your Android.mk file:

LOCAL_LDLIBS += -lOpenSLES

For more information about the OpenSL ES API, refer to OpenSL ES for Android

Android native application APIs

Starting from API level 9, you can write an entire Android app with native code, without using any Java.

Note: Writing your app in native code is not, in itself, enough for your app to run in the VM. Moreover, your app must still access most features of the Android platform via JNI.

This release provides the following native headers:

For more information about these headers, see the NDK API Reference documentation, as well as the comments in the headers, themselves. Also, for more information about the larger topic of writing native apps, see Native Activities and Applications.

When you include one or more of these headers, you must also link against the libandroid.so library. To link against libandroid.so, include the following line in your Android.mk file:

LOCAL_LDLIBS += -landroid

Android API level 14

Native API changes introduced in API level 14

  1. OpenMAX AL
  2. OpenSL ES

The NDK provides the following APIs for developing native code that runs on Android 4.0 system images and above.

OpenMAX AL

Android native multimedia handling is based on Khronos Group OpenMAX AL 1.0.1 API.

The standard OpenMAX AL headers <OMXAL/OpenMAXAL.h> and <OMXAL/OpenMAXAL_Platform.h> contain the declarations necessary for performing multimedia output from the native side of Android.

The NDK distribution of OpenMAX AL also provides Android-specific extensions. For information about these extensions, see the comments in <OMXAL/OpenMAXAL_Android.h>.

The system library libOpenMAXAL.so implements the public native multimedia functions. To link against this library, include the following line in your Android.mk file:

    LOCAL_LDLIBS += -lOpenMAXAL

For more information about this topic, see $NDK/docs/openmaxal/index.html, where $NDK is the root directory of your NDK installation.

OpenSL ES

OpenSL ES support for this Android API level adds PCM support. For more information about OpenSL ES support in the NDK, see OpenSL ES.

Android API level 18

The NDK provides the following APIs for developing native code that runs on Android 4.3 system images and above.

OpenGL ES 3.0

The standard OpenGL ES 3.0 headers <GLES3/gl3.h> and <GLES3/gl3ext.h> contain the declarations needed for performing OpenGL ES 3.0 rendering calls from native code. These rendering calls provide the ability to use the GLSL language to define and use vertex and fragment shaders.

To use OpenGL ES 3.0, link your native module against /system/lib/libGLESv3.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -lGLESv3

Not all devices support OpenGL ES 3.0. An app can query the OpenGL ES version string and extension string to determine whether the current device supports the features it needs. For information on how to perform this query, see the description of glGetString() in the OpenGL specification.

Additionally, you must put a <uses-feature> tag in your manifest file to indicate which version of OpenGL ES your application requires. For more information about the OpenGL ES settings for <uses-feature>, see OpenGL ES.

The gles3jni sample application provides a basic example of how to use OpenGL ES 3.0 with the NDK.

Android API level 21

The NDK provides the following APIs for developing native code that runs on Android 4.3 system images and above.

OpenGL ES 3.1

The standard OpenGL ES 3.1 headers <GLES3/gl31.h> and <GLES3/gl3ext.h> contain the declarations needed for performing OpenGL ES 3.1 rendering calls from native code. These rendering calls provide the ability to use the GLSL language to define and use vertex and fragment shaders.

To use OpenGL ES 3.1, link your native module against /system/lib/libGLESv3.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -lGLESv3

Not all devices support OpenGL ES 3.1. An app can query the OpenGL ES version string and extension string to determine whether the current device supports the features it needs. For information on how to perform this query, see the description of glGetString() in the OpenGL specification.

Additionally, you must put a <uses-feature> tag in your manifest file to indicate which version of OpenGL ES your application requires. For more information about the OpenGL ES settings for <uses-feature>, see OpenGL ES.

The gles3jni sample application provides a basic example of how to use OpenGL ES 3.1 with the NDK.

Note: The Android emulator does not support OpenGL ES 3.1 hardware emulation. Running and testing code that uses this API requires a real device with hardware that can support OpenGL ES 3.1.

Android API level 23

The NDK introduces the following APIs for developing native code that runs on Android 6.0 and higher system images.

Tracing

The native tracing API (<android/trace.h>) provides the native equivalent of the android.os.trace methods in the Java programming language. This API lets you trace named units of work in your native code by writing trace events to the system trace buffer. You can then collect and analyze the trace events by using the Systrace tool. For more information about using this API, see Native Tracing.

Android API level 24

Native API changes introduced in API level 24

  1. Vulkan
  2. Camera
  3. Choreographer
  4. Multinetwork
  5. EGL
  6. OpenGL ES 3.2

The NDK introduces the following APIs for developing native code that runs on Android 7.0 and higher system images.

Vulkan

Vulkan is a low-overhead, cross-platform API for high-performance 3D graphics rendering. Vulkan is an open standard maintained by the Khronos Group. The standard <vulkan/vulkan.h> header file contains the declarations needed to perform Vulkan rendering calls from your native code.

To learn more about using Vulkan in your Android apps, see the API documentation. For code samples, see the vulkan-basic-samples and android-vulkan-tutorials projects on GitHub.

Camera

The native camera API provides the native equivalent of the android.hardware.camera2 classes in the Java programming language. The native camera API lets you perform fine-grained photo capture and processing in your native code. Unlike the Java camera2 API, the native camera API does not support deprecated camera HAL 1.0 implementations (that is, the available camera list in the native camera API won’t list camera devices that have the LEGACY hardware level).

Choreographer

The native choreographer API (<android/choreographer.h>) is the native equivalent of the android.view.Choreographer class in Java. The native choreographer API gives you the ability to coordinate the timing of animations, input, and drawing in your native code. This API is useful for frame pacing by providing synchronization with vsync. For an example of how to use the choreographer API, see the choreographer-30fps directory in the Teapots sample project on GitHub.

Multinetwork

The native multinetwork API (<android/multinetwork.h>) gives native code access to the same functionality as the Java multi-networking APIs that were added in Android 5.0.

EGL

EGL support for Android API level 24 adds support for the following extensions:

For more information about EGL support in the NDK, see EGL.

OpenGL ES 3.2

The standard OpenGL ES 3.2 headers <GLES3/gl32.h> and <GLES3/gl3ext.h> contain the declarations needed for performing OpenGL ES 3.2 rendering calls from native code.

To use OpenGL ES 3.2, link your native module against /system/lib/libGLESv3.so by including the following line in your Android.mk file:

LOCAL_LDLIBS := -lGLESv3

Not all devices support OpenGL ES 3.2. An app can query the OpenGL ES version string and extension string to determine whether the current device supports the features it needs. For information on how to perform this query, see the description of glGetString() in the OpenGL specification.

Additionally, you must put a <uses-feature> tag in your manifest file to indicate which version of OpenGL ES your application requires. For more information about the OpenGL ES settings for <uses-feature>, see OpenGL ES.

Android API level 26

The NDK introduces the following APIs for developing native code that runs on Android O Developer Preview and higher system images.

AAudio

The NDK introduces the AAudio API (<aaudio/AAudio.h>) for high-performance audio apps that require low latency. Apps that use AAudio read and write data to audio streams. AAudio is intended to be an easier alternative than using OpenSL ES. For more information about using this API, see the AAudio developer guide.

Hardware Buffer

The NDK introduces two native APIs that let you create your own pipelines for cross-process buffer management.

The native hardware buffer API (<android/hardware_buffer.h>) lets you directly allocate buffers to create your own pipelines for cross-process buffer management. You can allocate a AHardwareBuffer struct and use it to obtain an EGLClientBuffer resource type via the eglGetNativeClientBufferANDROID extension. You can pass that buffer to eglCreateImageKHR to create an EGLImage resource type, which may then be bound to a texture via glEGLImageTargetTexture2DOES on supported devices. This can be useful for creating textures that may be shared cross-process.

The native hardware buffer JNI API ( <android/hardware_buffer_jni.h>) lets you obtain a HardwareBuffer object, which is a Parcelable and thus may be transported between two different processes. This gives your app similar capabilities as SurfaceFlinger (such as creating your own queue of buffers between processes) without accessing internal Android APIs.

Shared Memory

The shared memory API (<android/sharedmem.h>) is a wrapper around Android native shared memory. It can can be used for inter-process communication. Upon creation of shared memory, a file descriptor is returned as the handle. You can access the content in shared memory after mapping the file descriptor into a process's memory space by using mmap(). To remove the mapping, call munmap(). File descriptors can be exchanged with other process via UNIX domain sockets. The system releases allocated shared memory after associated file descriptors are closed and all memory maps are unmapped in all processes.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.