原生 API

本页概述了 NDK 中包含的库,并提供了指向 NDK API 参考文档中相关部分的链接,以及指向这些参考文档所在指南的链接。

使用原生 API

请执行以下两个步骤,以便使用 NDK 提供的库:

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

    • 如果您使用的是 ndk-build:将库添加到 Android.mk 中的 LOCAL_LDLIBS。请注意,您需要将前导 lib 替换为 -l。例如,若要链接到 libfoolibbar,您需要采用: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 上不存在单独的 libpthreadlibrt 库。该功能直接包含在 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_bufferANDROID_create_native_client_bufferANDROID_front_buffer_auto_refresh 扩展指令集的支持。

从 API 级别 9 开始提供。

库:libEGL

指南:EGL 原生平台接口

Vulkan

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

如需代码示例,请参阅 GitHub 上的 LunarG VulkanSamplesandroid-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 提供类似于 MediaExtractorMediaCodec 和其他相关 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 参考文档