原生 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。想瞭解更簡單的方法，請參閱「使用較新的 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++ 程式庫支援，請參閱 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 之前的 OS 版本。因此只要一律使用靜態 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 是一款用於高效能 3D 圖形算繪的低成本跨平台 API，也是由 Khronos Group 維護的開放式標準。標準 <vulkan/vulkan.h> 標頭檔案包含從程式碼執行 Vulkan 算繪呼叫所需的宣告。

如需程式碼範例，請參閱 GitHub 上的 LunarG VulkanSamples 和 android-vulkan-tutorials 專案。

凡是支援 API 級別 24 或以上級別的裝置，皆有 Vulkan 程式庫，但應用程式必須在執行階段檢查是否具有所需的 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 參考資料

同步 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，並將其用於取得 EGLClientBuffer 資源類型 (透過 eglGetNativeClientBufferANDROID 擴充功能取得)。您可以將這個緩衝區傳遞至 eglCreateImageKHR，以便建立 EGLImage 資源類型，接著，該資源類型可能會在支援的裝置上透過 glEGLImageTargetTexture2DOES 與紋理繫結。如要建立可以跨程序共用的紋理，這個方法便很適合。

您可以透過原生硬體緩衝區 JNI API (<android/hardware_buffer_jni.h>) 取得 HardwareBuffer 物件，此物件為 Parcelable 物件，可以在兩個不同程序之間傳輸。這讓應用程式可以使用與 SurfaceFlinger 類似的功能，例如在不同程序之間建立緩衝區佇列，而無需存取內部 Android API。

音訊

AAudio

AAudio 是目前支援的原生音訊 API。AAudio 取代了 OpenSL ES，可為需要低延遲音訊的高效能音訊應用程式提供更優質的支援。

從 API 級別 26 開始提供。

程式庫：libaaudio

指南：AAudio API 指南

參考資料：AAudio API 參考資料

OpenSL ES

OpenSL ES 是另一個原生音訊 API，NDK 也支援此 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 指南

參考資料：Neural Networks API 參考資料