原生 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 docs 文档。

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

  2. 使用 #include 包含代码中的相应头文件。

请注意，默认情况下无法调用比应用的 minSdkVersion 更新的 API，您必须通过 dlopen() 和 dlsym() 使用这些 API。如需了解更简单的方法，请参阅使用新版 API。

Core C/C++

C 库

<stdlib.h> 和 <stdio.h> 等标准 C11 库头文件照常提供。

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

数学函数有单独的 libm（遵循通行的 Unix 传统），但像 libc 一样，它会由构建系统自动链接。

提供 <dlfcn.h> 中的 dlopen(3) 和 dlsym(3) 等动态链接器功能，但您必须显式链接到 libdl。

库：libc/libm/libdl

C++ 库

提供 C++17 支持。如需了解详情，请参阅 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 头文件，并且 NDK 中包含的用于静态链接的 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 上下文和 Surface。

EGL 可让您通过原生代码执行以下操作：

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

API 级别 24 增加了对 EGL_KHR_mutable_render_buffer、ANDROID_create_native_client_buffer 和 ANDROID_front_buffer_auto_refresh 扩展指令集的支持。

从 API 级别 9 开始提供。

库：libEGL

指南：EGL 原生平台接口

Vulkan

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

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

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

从 API 级别 24 开始提供。

库：libvulkan

指南：Vulkan Graphics API 指南

位图

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

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

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

  3. 对像素缓冲区进行相应修改，以使其符合相应像素格式、宽度和其他特性。

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

从 API 级别 8 开始提供。

库：libjnigraphics

参考文档：位图 API 参考文档

同步 API

自 API 级别 26 开始提供。

库：libsync

参考文档：同步 API 参考文档

相机

原生相机 API 可执行精细的照片拍摄和处理。与 Java camera2 API 不同，原生相机 API 不支持已弃用的相机 HAL 1.0 实现（即原生相机 API 中的可用相机列表不会列出达到 LEGACY 硬件级别的相机设备）。

从 API 级别 24 开始提供。

库：libcamera2ndk

参考文档：相机 API 参考文档

媒体

libmediandk

媒体 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 原生端执行多媒体输出所需的声明。

OpenMAX AL 的 NDK 分发还提供 Android 专用扩展指令集。如需了解这些扩展指令集，请参阅 <OMXAL/OpenMAXAL_Android.h> 中的注释。

从 API 级别 14 开始提供。

库：libOpenMAXAL

Android 原生应用 API

如需了解详情，请参阅 Android NDK API 参考文档。

API 包括：

库：libandroid

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

完整参考文档：Android NDK API 参考文档

硬件缓冲区 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 指南

Neural Networks API

Neural Networks API (NNAPI) 为应用提供适用于设备端机器学习操作的硬件加速功能。此 API 支持在设备上创建、编译和执行模型。应用通常不会直接使用 NNAPI；相反，API 将通过机器学习库、框架和工具进行调用，以便开发者在 Android 设备上训练并部署其模型。

从 API 级别 27 开始提供。

库：libneuralnetworks

指南：神经网络指南

参考文档：Neural Networks API 参考文档