Android [Camera 原始碼] 版本支援(Version Support) Google官方文件（十四）
Google原始碼網地址連結：https://source.android.com/devices/camera
該Google Camera的文件為系列文章，文章列表：
overview
Camera3
HAL Subsystem
Metadata and Controls
3A Modes and State
Output and Cropping
Errors and Streams
Request Creation
External USB Cameras
Multi-Camera Support
Motion Tracking
Session Parameters
Single Producer,Multiple Consumer
Version Support
相機版本支援（Version Support）
本頁詳細介紹了 Camera HAL、API 和相關的 Android 相容性測試套件 (CTS) 測試中的版本差異，還介紹了在 Android 7.0 中為增強和提高相機框架安全性而進行的幾項架構更改，在 Android 8.0 中引入 Treble，以及供應商在其相機實現中為支援這些更改而必須進行的更新。
術語
本頁中用到以下術語：
Camera API1
Android 4.4 或更低版本裝置上的應用級相機框架，通過 android.hardware.Camera 類提供。
Camera API2
Android 5.0 及更高版本裝置上的應用級相機框架，通過 android.hardware.camera2 包提供。
Camera HAL
由 SoC 供應商實現的相機模組層。該應用級公共框架基於 Camera HAL 構建而成。
Camera HAL3.1
隨 Android 4.4 釋出的相機裝置 HAL 版本。
Camera HAL3.2
隨 Android 5.0 釋出的相機裝置 HAL 版本。
Camera API1 CTS
在 Camera API1 之上執行的相機相容性測試套件 (CTS) 測試集。
Camera API2 CTS
在 Camera API2 之上執行的另一個相機 CTS 測試集。
Treble
利用新的供應商介面，將供應商實現（由晶片製造商編寫的裝置專屬底層軟體）與 Android 作業系統框架分離開來。
HIDL
HAL 介面定義語言隨 Treble 引入，用於指定 HAL 和其使用者之間的介面。
VTS
供應商測試套件隨 Treble 引入。
相機 API
Android 包含以下相機 API。
Camera API1
Android 5.0 已棄用 Camera API1，而且隨著新平臺開發的重點放在 Camera API2 上，Camera API1 會逐漸被淘汰。但是，淘汰期限將會很長，而且在一段時間內新 Android 版本會繼續支援 Camera API1 應用。具體來說，將繼續為以下內容提供支援：
- 供應用使用的 Camera API1 介面。在 Camera API1 之上構建的相機應用應該像在執行早期 Android 版本的裝置上一樣工作。
- Camera HAL 版本。包括對 Camera HAL1.0 的支援。
Camera API2
Camera API2 框架為應用提供更接近底層的相機控制元件，包括高效的零複製連拍/視訊流以及曝光、增益、白平衡增益、顏色轉換、去噪、銳化等方面的每幀控制元件。有關詳細資訊，請觀看 Google I/O 視訊概覽。
Android 5.0 及更高版本提供 Camera API2；但是，執行 Android 5.0 及更高版本的裝置可能並不支援所有 Camera API2 功能。應用可通過 Camera API2 介面查詢 android.info.supportedHardwareLevel 屬性。該屬性會報告以下支援級別之一：
- LEGACY（舊版）。這些裝置通過 Camera API2 介面為應用提供功能，而且這些功能與通過 Camera API1 介面提供給應用的功能大致相同。舊版框架程式碼在概念上將 Camera API2 呼叫轉換為 Camera API1 呼叫；舊版裝置不支援 Camera API2 功能，例如每幀控制元件。
- LIMITED（有限）。這些裝置支援部分（但不是全部）Camera API2 功能，並且必須使用 Camera HAL 3.2 或更高版本。
- FULL（全面）。這些裝置支援 Camera API2 的所有主要功能，並且必須使用 Camera HAL 3.2 或更高版本以及 Android 5.0 或更高版本。
- LEVEL_3（級別 3）：這些裝置支援 YUV 重新處理和 RAW 圖片捕獲，以及其他輸出流配置。
- EXTERNAL（外部）：這些裝置類似於 LIMITED 裝置，但有一些例外情況；例如，某些感測器或鏡頭資訊可能未被報告或具有較不穩定的幀速率。此級別用於外部相機（如 USB 網路攝像頭）。
各項功能通過 Camera API2 介面中的 android.request.availableCapabilities 屬性提供。FULL 裝置需要具備 MANUAL_SENSOR 和 MANUAL_POST_PROCESSING 等功能。但即使是 FULL 裝置，也並非必須實現 RAW 功能。 LIMITED 裝置可以提供這些功能的任何子集，甚至可以不提供其中任何功能。但是，必須始終定義 BACKWARD_COMPATIBLE 功能。
裝置支援的硬體級別及其支援的特定 Camera API2 功能採用以下功能標記的形式指明，以允許 Google Play 過濾 Camera API2 相機應用。
- android.hardware.camera.hardware_level.full
- android.hardware.camera.capability.raw
- android.hardware.camera.capability.manual_sensor
- android.hardware.camera.capability.manual_post_processing
CTS 要求
執行 Android 5.0 及更高版本的裝置必須通過 Camera API1 CTS、Camera API2 CTS 和 CTS 驗證程式相機測試。
不具備 Camera HAL3.2 實現且不能支援完整的 Camera API2 介面的裝置仍必須通過 Camera API2 CTS 測試。但是，該裝置將在 Camera API2 LEGACY 模式下執行（在該模式下，Camera API2 呼叫在概念上對映到 Camera API1 呼叫），因此與 Camera API1 之上的特徵或功能相關的任何 Camera API2 CTS 測試都將自動跳過。
在舊版裝置上，未跳過的 Camera API2 CTS 測試使用現有的公共 Camera API1 介面和功能，沒有新的要求。顯示的錯誤（並導致 Camera API2 CTS 失敗）是裝置現有 Camera HAL 中已經存在的錯誤，因此可由現有 Camera API1 應用找到。我們預計不會出現太多此類錯誤（但是，任何此類錯誤均必須修復，才能通過 Camera API2 CTS 測試）。
VTS 要求
採用繫結式 HAL 實現的執行 Android 8.0 及更高版本的裝置必須通過相機 VTS 測試。
相機框架強化
為了增強媒體和相機框架安全性，Android 7.0 已將相機服務從 mediaserver 中移出。從 Android 8.0 開始，每個繫結式相機 HAL 都會在與相機服務不同的程序中執行。供應商可能需要根據正在使用的 API 和 HAL 版本對 Camera HAL 進行更改。以下部分詳細介紹了在 HAL1 和 HAL3 的 AP1 和 AP2 中進行的架構更改，以及常規要求。
API1 的架構更改
API1 視訊錄製可能會假定相機和視訊編碼器存在於同一程序中。在以下物件上使用 API1 時：
- HAL3，其中相機服務使用 BufferQueue 在程序之間傳遞緩衝區，不需要供應商更新。
圖 1. HAL3 上 API1 中的 Android 7.0 相機和媒體堆疊。
- HAL1（支援在視訊緩衝區中傳遞元資料），供應商必須更新 HAL 才能使用 kMetadataBufferTypeNativeHandleSource（Android 7.0 中不再支援 kMetadataBufferTypeCameraSource）。
圖 2. HAL1 上 API1 中的 Android 7.0 相機和媒體堆疊。
API2 的架構更改
對於 HAL1 或 HAL3 上的 API2，BufferQueue 會傳遞緩衝區，以便這些路徑能繼續工作。Android 7.0 的 API2 架構：
- 若在 HAL1 上，則不受 cameraservice 移動的影響，並且不需要供應商更新。
- 若在 HAL3 上，則會受到 cameraservice 移動的影響，但不需要供應商更新：
其他要求
為增強媒體和相機框架安全性而進行的架構更改包括以下附加裝置要求。
- 常規。由於 IPC，裝置需要額外頻寬，這可能會影響對時間敏感的相機使用情況，例如高速視訊錄製。供應商可以執行 android.hardware.camera2.cts.PerformanceTest 和 Google 相機應用，以進行 120/240 FPS 高速視訊錄製，從而衡量實際影響。裝置還需要少量額外的 RAM 來建立新程序。
- 在視訊緩衝區中傳遞元資料（僅限 HAL1）。如果 HAL1 在視訊緩衝區中儲存元資料而非實際的 YUV 幀資料，則 HAL 必須使用 kMetadataBufferTypeNativeHandleSource 作為元資料緩衝區型別，並在視訊緩衝區中傳遞 VideoNativeHandleMetadata（kMetadataBufferTypeCameraSource 在 Android 7.0 中不再受支援）。通過 VideoNativeHandleMetadata，相機和媒體框架能夠正確地對原生控制代碼進行序列化和反序列化，從而在程序之間傳遞視訊緩衝區。
- 緩衝區控制代碼地址並不總是儲存相同的緩衝區（僅限 HAL3）。對於每個捕獲請求，HAL3 會獲取緩衝區控制代碼的地址。HAL 不能使用地址來識別緩衝區，因為地址可能會在 HAL 返回緩衝區之後儲存另一個緩衝區控制代碼。您必須更新 HAL，以便使用緩衝區控制代碼來標識緩衝區。例如：HAL 接收緩衝區控制代碼地址 A，該地址儲存緩衝區控制代碼 A。在 HAL 返回緩衝區控制代碼 A 之後，緩衝區控制代碼地址 A 可能在 HAL 下次接收到它時儲存緩衝區控制代碼 B。
- 更新用於 cameraserver 的 SELinux 策略。如果裝置特定的 SELinux 策略向 mediaserver 授予執行相機的許可權，則您必須更新 SELinux 策略，以授予 cameraserver 正確的許可權。我們建議不要為 cameraserver 複製 mediaserver 的 SELinux 策略（因為 mediaserver 和 cameraserver 通常需要系統中的不同資源）。Cameraserver 應僅具有執行相機功能所需的許可權，並且 mediaserver 中任何不必要的相機相關許可權均應被移除。
- 將相機 HAL 與 cameraserver 分離開。此外，搭載 Android 8.0 或更高版本的裝置會在與 cameraserver 不同的程序中分離繫結式相機 HAL。IPC 會通過 HIDL 定義的介面。
驗證
對於包含相機且執行 Android 7.0 的所有裝置，請通過執行 Android 7.0 CTS 來驗證相關實現。儘管 Android 7.0 不包含驗證相機服務更改的新 CTS 測試，但如果您尚未進行上述更新，則現有 CTS 測試將失敗。
對於包含相機並執行 Android 8.0 或更高版本的所有裝置，請通過執行 VTS 來驗證供應商實現。
Camera HAL 版本歷史記錄
要獲取可用於評估 Android Camera HAL 的測試列表，請參閱 Camera HAL 測試核對清單。
Android 8.0
Android 8.0 版本引入了 Treble。引入 Treble 後，供應商相機 HAL 實現必須為繫結式。Android 8.0 還包含對相機服務的以下主要增強功能：
- 共享 surface - 可讓多個 surface 共享同一個 OutputConfiguration
- 適用於自定義相機模式的系統 API
- onCaptureQueueEmpty
有關這些功能的詳細資訊，請參閱以下部分。
共享 surface
藉助此功能，只需一組緩衝區就可以驅動兩個輸出（例如預覽和視訊編碼），從而降低功耗和記憶體消耗。要支援此功能，裝置製造商需要確保其相機 HAL 和 gralloc HAL 實現可以建立將由多個不同消耗方（而不是僅一個消耗方；例如 Hardware Composer/GPU 和視訊編碼器）使用的 gralloc 緩衝區。相機服務會將消耗方使用情況標記傳遞到相機 HAL 和 gralloc HAL；它們需要分配正確的緩衝區型別，或者相機 HAL 需要返回一個表明該消耗方組合不受支援的錯誤。
有關其他詳細資訊，請參閱 enableSurfaceSharing 開發者文件。
適用於自定義相機模式的系統 API
公共相機 API 定義了兩種操作模式：正常模式和受限高速錄製模式。這兩種模式的語義截然不同；高速模式受限於一次最多隻能有兩個具體輸出等。各個原始裝置製造商 (OEM) 已表現出極大的興趣想要針對特定於硬體的功能定義其他自定義模式。說白了，該模式只是一個傳遞到 configure_streams 的整數。請參閱：hardware/camera/device/3.2/ICameraDeviceSession#configurestreams。
此功能包括一個系統 API 呼叫，OEM 相機應用可以使用該呼叫來啟用自定義模式。這些自定義模式必須以整數值 0x8000 開頭，以避免與未來新增到公共 API 的模式發生衝突。
要支援這一功能，OEM 只需將新模式新增到其 HAL 即可，傳遞至 HAL 的這一整數會在 configure_streams 上觸發該模式，然後 OEM 就可以讓其自定義相機應用使用系統 API。
此方法的名稱是 android.hardware.camera2.CameraDevice#createCustomCaptureSession。 請參閱：frameworks/base/core/java/android/hardware/camera2/CameraDevice.java#805。
- 注意：在 Android 8.1 版本中，應用必須預安裝到系統映像上才能訪問此 API。
onCaptureQueueEmpty
此 API 的目的是通過儘可能讓請求佇列為空，來縮短控制更改（如縮放）的延遲時間。onCaptureQueueEmpty 不需要 HAL 發揮作用；它只是一種框架端補充。想要利用此 API 的應用需要向該回調新增監聽器，並相應地做出響應。通常，響應方式是向相機裝置傳送另一個捕獲請求。
相機 HIDL 介面
相機 HIDL 介面在相機 HAL 介面（使用以 HIDL 定義的穩定 API）基礎上進行了全面改造。在最近的舊版本 3.4 和 2.4（針對相機模組）中引入的所有功能和相機功能也是 HIDL 定義的一部分。
3.4
對受支援的元資料添加了少許內容並對 data_space 支援進行了更改：
- 如果支援 RAW_OPAQUE 格式，則必須強制新增 ANDROID_SENSOR_OPAQUE_RAW_SIZE 靜態元資料。
- 如果支援任何 RAW 格式，則必須強制新增 ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE 靜態元資料。
- 使用資料空間編碼的版本 0 定義，將 camera3_stream_t data_space 欄位切換為更靈活的定義。
- 可用於 HALv3.2 或更高版本的常規元資料新增項：
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
ANDROID_SENSOR_OPAQUE_RAW_SIZE
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
3.3
擴充套件功能 HAL 的小修訂：
- OPAQUE 和 YUV 重新處理 API 更新。
- 對深度輸出緩衝區的基本支援。
- 為 camera3_stream_t 添加了 data_space 欄位。
- 為 camera3_stream_t 添加了旋轉欄位。
- 為 camera3_stream_configuration_t 添加了 camera3 流配置操作模式。
3.2
擴充套件功能 HAL 的小修訂：
- 棄用了 get_metadata_vendor_tag_ops。在 camera_common.h 中改用 get_vendor_tag_ops。
- 棄用了 register_stream_buffers。框架在 process_capture_request 中提供給 HAL 的所有 gralloc 緩衝區在任何時候可能都是新的。
- 添加了部分結果支援。在獲得完整結果之前，通過多次呼叫 process_capture_result 可以獲得可用結果的子集。
- 為 camera3_request_template 添加了手動模板。應用可以使用此模板直接控制捕獲設定。
- 重新制定雙向和輸入流規範。
- 更改輸入緩衝區返回路徑。緩衝區在 process_capture_result 而不是 process_capture_request 中返回。
3.1
擴充套件功能 HAL 的小修訂：
- configure_streams 將消耗方使用標記傳遞給 HAL。
- 重新整理呼叫以儘可能快地丟棄所有傳輸中的請求/緩衝區。
3.0
擴充套件功能 HAL 的首次修訂：
- 重要版本更改，因為 ABI 完全不同。在所需的硬體功能或操作模式方面，與 2.0 相比沒有更改。
- 重新設計了輸入請求和流佇列介面：框架呼叫 HAL 且後續請求和流緩衝區已經出隊。包含同步框架支援，這是高效實現所必需的。
- 已將觸發器移動到請求中，將大多數通知移動到結果中。
- 將框架中的所有回調合併到一個結構中，並將所有設定方法合併到單個 initialize() 呼叫中。
- 將資訊流配置整合到單個呼叫中，從而簡化資訊流管理。雙向資訊流替代 STREAM_FROM_STREAM 構造。
- 為較舊/受限的硬體裝置限制了模式語義。
2.0
初始版本的擴充套件功能 HAL (Android 4.2) [camera2.h]：
- 足夠用於實現現有的 android.hardware.Camera API。
- 允許用於相機服務層中的 ZSL 佇列。
- 未針對任何新功能（如手動捕獲控制、Bayer RAW 捕獲，RAW 資料的重新處理等）進行測試。
1.0
初始 Android Camera HAL (Android 4.0) [camera.h]：
- 已從 C++ CameraHardwareInterface 抽象層進行轉換。
- 支援 android.hardware.Camera API。
相機模組版本歷史記錄
本部分包含相機硬體模組的模組版本控制資訊（基於 camera_module_t.common.module_api_version）。兩個最重要的十六進位制數字表示 Major 版本，而兩個最不重要的數字表示 Minor 版本。
2_4
此相機模組版本添加了以下 API 更改：
- 手電筒模式支援。框架可以為具有閃光燈元件的任何相機裝置開啟手電筒模式，而無需開啟相機裝置。相機裝置對閃光燈元件的訪問優先順序高於相機模組；如果已通過模組介面啟用手電筒，則開啟相機裝置會關閉手電筒。當出現任何資源衝突時（例如呼叫 open() 以開啟相機裝置），Camera HAL 模組必須通過手電筒模式狀態回撥告知框架手電筒模式已關閉。
- 外部相機（如 USB 熱插拔相機）支援。僅當相機已連線且準備好用於外部熱插拔相機時，API 更新才會指明相機靜態資訊可用。當相機狀態不是 CAMERA_DEVICE_STATUS_PRESENT 時，獲取靜態資訊的呼叫將為無效呼叫。框架僅依賴裝置狀態更改回調來管理可用的外部相機列表。
- 相機仲裁提示。添加了相關支援，以明確指明可以同時開啟和使用的相機裝置數量。要指定有效的裝置組合，應始終在由 get_camera_info 呼叫返回的 camera_info 結構中設定 resource_cost 和 conflicting_devices 欄位。
- 模組初始化方法。在載入 HAL 模組後由相機服務呼叫，以允許初始化 HAL 一次。該方法在呼叫任何其他模組方法之前呼叫。
2_3
該相機模組版本添加了對開啟舊版 Camera HAL 裝置的支援。如果同一裝置可以支援多個裝置 API 版本，則框架利用該支援可以開啟相機裝置作為較低裝置 HAL 版本的 HAL 裝置。標準硬體模組開啟呼叫 (common.methods->open) 會繼續使用支援的最新版本（即 camera_info_t.device_version 中列出的版本）開啟相機裝置。
2_2
該相機模組版本添加了模組供應商標記支援，並且棄用了以前只能通過開啟裝置才可訪問的舊版 vendor_tag_query_ops。
2_1
該相機模組版本添加了對從 Camera HAL 模組到框架的非同步回撥支援，利用該支援可以通知框架關於相機模組狀態的更改。提供有效 set_callbacks() 方法的模組必須至少報告此版本號。
2_0
報告此版本號的相機模組會實現相機模組 HAL 介面的第二個版本。可通過此模組開啟的相機裝置可能支援 1.0 版本或 2.0 版本的相機裝置 HAL 介面。camera_info 的 device_version 欄位始終有效；如果 device_version 欄位為 2.0 或更高版本，則 camera_info 的 static_camera_characteristics 欄位有效。
1_0
報告這些版本號的相機模組實現了初始相機模組 HAL 介面。可通過此模組開啟的所有相機裝置僅支援版本 1 的相機裝置 HAL。camera_info 的 device_version 和 static_camera_characteristics 欄位無效。只有 android.hardware.Camera API 受該模組及其裝置的支援。