camera3_capture_result 結構體參考資料
#include <
camera3.h
>
資料欄位 |
|
uint32_t | frame_number |
const camera_metadata_t * | 結果 |
uint32_t | num_output_buffers |
const camera3_stream_buffer_t * | output_buffers |
const camera3_stream_buffer_t * | input_buffer |
uint32_t | partial_result |
詳細說明
camera3_capture_result_t:
相機 HAL 裝置單次擷取/重新處理的結果。這會透過 process_capture_result() 以非同步方式傳送至架構,以回應透過 process_capture_request() 傳送至 HAL 的單一擷取要求。HAL 可能會針對每個要求執行多個 process_capture_result() 呼叫。
每個呼叫都具有相同的框架編號,可能包含部分輸出緩衝區和/或結果中繼資料。每個指定影格編號只能提供一次中繼資料;所有其他呼叫都必須將結果中繼資料設為 NULL。
結果結構體包含此擷取作業的輸出中繼資料,以及已/將為此擷取作業填入的輸出緩衝區組合。每個輸出緩衝區可能都會附帶釋放同步化圍欄,以便在讀取前等待,以防緩衝區尚未由 HAL 填入資料。
>= CAMERA_DEVICE_API_VERSION_3_2:
中繼資料可為單一影格編號提供多次。架構會將每個部分結果組合成總結果集,藉此累積最終結果集。
如果在要求中提供輸入緩衝區,HAL 必須在其中一個 process_capture_result 呼叫中傳回該緩衝區,而該呼叫可能只會傳回輸入緩衝區,而不會傳回中繼資料和輸出緩衝區;同步化圍籬必須以與輸出緩衝區相同的方式處理。
效能考量事項:
應用程式也會立即收到這些部分結果,因此我們強烈建議您傳送部分結果,以便在管道初期傳送已知結果,避免整體管道延遲。
典型用途可能是在管道中途計算自動對焦狀態;透過立即將狀態傳回至架構,我們可獲得 50% 的效能提升,並提升自動對焦的回應速度。
欄位說明文件
uint32_t frame_number |
影格編號是架構在提交要求時設定的遞增整數,用於單獨識別這項擷取作業。這項參數也用於在傳送至 camera3_callback_ops_t.notify() 的非同步通知中識別要求。
const camera3_stream_buffer_t * input_buffer |
>= CAMERA_DEVICE_API_VERSION_3_2:
此擷取作業的輸入串流緩衝區句柄。在 HAL 呼叫 process_capture_result() 時,緩衝區可能尚未使用;在重複使用緩衝區之前,架構會等待 HAL 提供的釋放同步區隔。
HAL 應以與 output_buffers 相同的方式處理同步化柵欄。
每個要求只能傳送一個輸入緩衝區。與輸出緩衝區類似,HAL 必須維持傳回輸入緩衝區的順序。
效能考量事項:
應盡早傳回輸入緩衝區。如果 HAL 支援同步柵欄,則可呼叫 process_capture_result,以便在同步柵欄適當設定的情況下將其傳回。如果不支援同步化圍欄,則緩衝區只能在使用時傳回,這可能需要很長的時間;HAL 可能會選擇複製這個輸入緩衝區,以便加快緩衝區傳回的速度。
uint32_t num_output_buffers |
const camera3_stream_buffer_t * output_buffers |
此擷取作業的輸出串流緩衝區句柄。在 HAL 呼叫 process_capture_result() 時,這些緩衝區可能尚未填滿;在讀取緩衝區之前,架構會等待 HAL 提供的釋放同步區隔。
HAL 必須將串流緩衝區的釋放同步化圍欄設為有效的同步 fd,如果緩衝區已填滿,則設為 -1。
如果 HAL 在處理緩衝區時發生錯誤,且緩衝區未填滿,則必須將緩衝區的狀態欄位設為 CAMERA3_BUFFER_STATUS_ERROR。如果 HAL 在遇到錯誤前未等待取得柵欄,則應將取得柵欄複製到釋放柵欄,讓架構在重複使用緩衝區前等待柵欄。
所有輸出緩衝區的取得圍欄都必須設為 -1。如果 num_output_buffers 為零,這個值可能為 NULL。在這種情況下,HAL 必須至少再發出一個 process_capture_result 呼叫,才能提供輸出緩衝區。
當 process_capture_result 以畫格的新緩衝區呼叫時,該相應串流的所有先前畫格緩衝區都必須已傳送 (柵欄不必已發出訊號)。
>= CAMERA_DEVICE_API_VERSION_3_2:
影格 Gralloc 緩衝區可能會在對應的 SHUTTER 通知之前傳送至架構。
效能考量事項:
除非透過 SHUTTER notify() 呼叫收到曝光開始時間戳記,否則傳送至架構的緩衝區不會調度至應用程式層。強烈建議盡快調度該呼叫。
uint32_t partial_result |
>= CAMERA_DEVICE_API_VERSION_3_2:
為了充分利用部分結果,HAL 必須將靜態中繼資料 android.request.partialResultCount 設為每個影格會傳送的部分結果數量。
每個含有部分結果的新擷取結果都必須將這個欄位 (partial_result) 設為 1 到 android.request.partialResultCount 之間的獨特值 (包含 1 和 android.request.partialResultCount)。
如果 HAL 不想使用這項功能,就不得將 android.request.partialResultCount 或 partial_result 設為 1 以外的值。
如果擷取結果只包含緩衝區,且不含中繼資料,則必須將這個值設為 0。
const camera_metadata_t * result |
此擷取結果的中繼資料。這項資訊包含最終擷取參數、擷取和後製硬體的狀態、3A 演算法狀態 (如果已啟用),以及任何已啟用的統計單位的輸出內容。
只有一個 process_capture_result() 呼叫 (帶有指定 frame_number) 可能包含結果中繼資料。所有其他呼叫相同 frame_number 的呼叫都必須將此值設為 NULL。
如果產生結果中繼資料時發生錯誤,結果必須是空的中繼資料緩衝區,且必須使用 ERROR_RESULT 呼叫 notify()。
>= CAMERA_DEVICE_API_VERSION_3_2:
多次呼叫 process_capture_result() 時,如果指定 frame_number,可能會包含結果中繼資料。
提交的部分中繼資料不應包含先前針對特定影格傳回的部分結果中所傳回的中繼資料鍵。該影格中的每個新部分結果也必須設定不同的 partial_result 值。
如果 notify 已使用 ERROR_RESULT 呼叫,則該影格後續的所有部分結果都會遭到架構忽略。
這個結構體的說明文件是由下列檔案產生:
- hardware/libhardware/include/hardware/ camera3.h