原生 API

本页概括介绍了 NDK 中包含的库，并提供了指向相关 NDK API 参考资料以及现有指南的链接。

使用原生 API

使用 NDK 提供的库需要执行两个步骤

  1. 告知构建系统链接到该库。

    • 如果您使用的是 ndk-build：将该库添加到您的 Android.mk 中的 LOCAL_LDLIBS。请注意，您需要去掉开头的 lib，然后使用 -l。例如，要链接到 libfoo 和 libbar，您可以这样写：makefile LOCAL_LDLIBS := -lfoo -lbar

      如需详细了解 LOCAL_LDLIBS，请参阅 Android.mk 文档。

    • 如果您使用的是 CMake：按照 Studio 的 添加 NDK API 文档中的说明进行操作。

  2. 在代码中 #include 相应的头文件。

请注意，默认情况下，比应用的 minSdkVersion 新的 API 不会可调用，您必须改用 dlopen() 和 dlsym() 来使用它们。如需更简单的方法，请参阅使用较新的 API。

核心 C/C++

C 库

标准 C11 库头文件，例如 <stdlib.h> 和 <stdio.h>，通常可用。

请注意，在 Android 上，与 Linux 不同，没有单独的 libpthread 或 librt 库。该功能直接包含在 libc 中，无需显式链接。

有一个单独的 libm 用于数学函数（遵循通常的 Unix 传统），但与 libc 一样，它会被构建系统自动链接。

<dlfcn.h> 中的动态链接器功能（例如 dlopen(3) 和 dlsym(3)）可用，但您必须显式链接到 libdl。

库：libc / libm / libdl

C++ 库

C++17 支持可用。有关 C++ 库支持的更多信息，请参阅C++ 库支持。

日志记录

<android/log.h> 包含用于向 logcat 记录日志的 API。

自 API 级别 3 起可用。

库：liblog

参考：日志记录

跟踪

原生跟踪 API <android/trace.h> 提供了 Java 编程语言中 android.os.Trace 类的原生等效功能。通过此 API，您可以通过将跟踪事件写入系统跟踪缓冲区来跟踪代码中有名称的工作单元。然后，您可以使用 Systrace 工具收集和分析跟踪事件。

自 API 级别 23 起可用。

库：libandroid

指南：原生跟踪

zlib 压缩

您可以通过包含 <zlib.h> 并链接到 libz 来使用 Zlib 压缩库。

NDK 发布时总是包含最新的 zlib 头文件，用于静态链接的 libz.a 版本始终与头文件版本相同，但用于动态链接的 libz.so 来自设备，版本取决于该设备上发布的版本。特别地，这意味着您构建时使用的头文件与设备上的 zlib 版本不匹配，因此此处尤其适用于关于不对实现细节做任何假设的常见警告。我们不知道公共 API 有任何问题，但特别是结构布局随时间发生了变化，并且很可能继续变化。请注意，后期 zlib 版本中的新 API 显然不会在早于该 API 的操作系统版本上提供。可以通过始终使用静态 libz.a 而不是 libz.so 来避免所有这些问题（代价是增加 APK 大小）。

自 API 级别 3 起可用（但请参阅上面的注意事项）。

库：libz

图形

OpenGL ES 1.0 - 3.2

标准 OpenGL ES 1.x 头文件（<GLES/gl.h> 和 <GLES/glext.h>）、2.0 头文件（<GLES2/gl2.h> 和 <GLES2/gl2ext.h>）、3.0 头文件（<GLES3/gl3.h> 和 <GLES3/gl3ext.h>）、3.1 头文件（<GLES3/gl31.h> 和 <GLES3/gl3ext.h>）以及 3.2 头文件（<GLES3/gl32.h> 和 <GLES3/gl3ext.h>）包含了 OpenGL ES 所需的声明。

要使用 OpenGL ES 1.x，请将您的原生模块链接到 libGLESv1_CM。

要使用 OpenGL ES 2.0，请将您的原生模块链接到 libGLESv2。

要使用 OpenGL ES 3.x，请将您的原生模块链接到 libGLESv3。

所有基于 Android 的设备都支持 OpenGL ES 1.0 和 2.0。

只有具备所需 GPU 的 Android 设备才完全支持更高版本的 OpenGL ES，但库存在于所有支持引入这些库的 API 级别的设备上。链接到库是安全的，但应用必须查询 OpenGL ES 版本字符串和扩展字符串，以确定当前设备是否支持其所需的功能。有关如何执行此查询的信息，请参阅 OpenGL 规范中关于 glGetString() 的说明。

此外，您必须在清单文件中放置一个 <uses-feature> 标记，以指明您所需的 OpenGL ES 版本。

OpenGL ES 1.0 自 API 级别 4 起可用。

OpenGL ES 2.0 自 API 级别 5 起可用。

OpenGL ES 3.0 自 API 级别 18 起可用。

OpenGL ES 3.1 自 API 级别 21 起可用。

OpenGL ES 3.2 自 API 级别 24 起可用。

EGL

EGL 通过 <EGL/egl.h> 和 <EGL/eglext.h> 头文件提供原生平台接口，用于分配和管理 OpenGL ES 上下文和表面。

EGL 允许您从原生代码执行以下操作

  • 列出支持的 EGL 配置。
  • 分配和释放 OpenGL ES 表面。
  • 创建和销毁 OpenGL ES 上下文。
  • 交换或翻转表面。

API 级别 24 添加了对 EGL_KHR_mutable_render_buffer、ANDROID_create_native_client_buffer 和 ANDROID_front_buffer_auto_refresh 扩展的支持。

自 API 级别 9 起可用。

库：libEGL

指南：EGL 原生平台接口

Vulkan

Vulkan 是一种低开销、跨平台 API，用于高性能 3D 图形渲染。Vulkan 是由 Khronos Group 维护的开放标准。标准 <vulkan/vulkan.h> 头文件包含从您的代码执行 Vulkan 渲染调用所需的声明。

有关代码示例，请参阅 GitHub 上的 LunarG VulkanSamples 和 android-vulkan-tutorials 项目。

Vulkan 库存在于所有支持 API 级别 24 或更高版本的设备上，但应用必须在运行时检查所需的 GPU 硬件支持是否可用。不支持 Vulkan 的设备将从 vkEnumeratePhysicalDevices 返回零个设备。

自 API 级别 24 起可用。

库：libvulkan

指南：Vulkan 图形 API 指南

位图

libjnigraphics 库公开了允许访问 Java Bitmap 对象的像素缓冲区的 API。工作流程如下：

  1. 调用 AndroidBitmap_getInfo() 以检索给定位图句柄的信息，例如宽度和高度。

  2. 调用 AndroidBitmap_lockPixels() 以锁定像素缓冲区并检索其指针。这样做可确保在应用调用 AndroidBitmap_unlockPixels() 之前，像素不会移动。

  3. 根据其像素格式、宽度和其他特性适当修改像素缓冲区。

  4. 调用 AndroidBitmap_unlockPixels() 解锁缓冲区。

自 API 级别 8 起可用。

库：libjnigraphics

参考：位图 API 参考

Sync API

自 API 级别 26 起可用。

库：libsync

参考：Sync API 参考

相机

原生相机 API 执行精细的照片捕捉和处理。与 Java camera2 API 不同，原生相机 API 不支持已弃用的 camera HAL 1.0 实现（也就是说，原生相机 API 中的可用相机列表不会列出具有 LEGACY 硬件级别的相机设备）。

自 API 级别 24 起可用。

库：libcamera2ndk

参考：相机 API 参考

媒体

libmediandk

Media API 提供了类似于 MediaExtractor、MediaCodec 和其他相关 Java API 的低级原生接口。

库：libmediandk

参考：媒体 API 参考

OpenMAX AL

Android 原生多媒体处理基于 Khronos Group OpenMAX AL 1.0.1 API。

标准 OpenMAX AL 头文件 <OMXAL/OpenMAXAL.h> 和 <OMXAL/OpenMAXAL_Platform.h> 包含从 Android 原生端执行多媒体输出所需的声明。

NDK 分发的 OpenMAX AL 还提供了 Android 特定的扩展。有关这些扩展的信息，请参阅 <OMXAL/OpenMAXAL_Android.h> 中的注释。

自 API 级别 14 起可用。

库：libOpenMAXAL

Android 原生应用 API

有关更多信息，请参阅 Android NDK API 参考文档。

API 包括

库：libandroid

库：用于较新原生窗口功能的 libnativewindow

完整参考：Android NDK API 参考

Binder API

Binder API 允许您在进程之间创建通信通道。这是 Android 进程间通信的低级实现。如果可能，首选更高级别的组件。但是，此库可用于高级用例。

库：libbinder_ndk

参考：Binder

硬件缓冲区 API

有两个原生 API 允许您创建自己的跨进程缓冲区管理管道。

原生硬件缓冲区 API <android/hardware_buffer.h> 允许您直接分配缓冲区，以创建自己的跨进程缓冲区管理管道。您可以分配一个 AHardwareBuffer 并使用它通过 eglGetNativeClientBufferANDROID 扩展获取 EGLClientBuffer 资源类型。您可以将该缓冲区传递给 eglCreateImageKHR 以创建 EGLImage 资源类型，然后在支持的设备上通过 glEGLImageTargetTexture2DOES 将其绑定到纹理。这对于创建可在进程间共享的纹理非常有用。

原生硬件缓冲区 JNI API (<android/hardware_buffer_jni.h>) 允许您获取一个 HardwareBuffer 对象，该对象是 Parcelable，因此可以在两个不同的进程之间传输。这为您的应用提供了与 SurfaceFlinger 类似的功能，例如在进程之间创建自己的缓冲区队列，而无需访问 Android 内部 API。

音频

AAudio

AAudio 是当前支持的原生音频 API。它取代了 OpenSL ES，并为需要低延迟音频的高性能音频应用提供了更好的支持。

自 API 级别 26 起可用。

库：libaaudio

指南：AAudio API 指南

参考：AAudio API 参考

OpenSL ES

OpenSL ES 是另一个也受支持的原生音频 API，但请参阅下面指南中的注意事项。

自 API 级别 9 起可用。API 级别 14 添加了 PCM 支持。

库：libOpenSLES

指南：Android 版 OpenSL ES 指南

神经网络 API

神经网络 API (NNAPI) 为应用提供设备端机器学习操作的硬件加速。该 API 支持设备端模型的创建、编译和执行。应用通常不会直接使用 NNAPI；相反，该 API 旨在供机器学习库、框架和工具调用，这些工具使开发者能够训练他们的模型并将其部署到 Android 设备上。

自 API 级别 27 起可用。

库：libneuralnetworks

指南：神经网络指南

参考：神经网络 API 参考