camera3_device_ops 結構體參考資料

configure_streams：

僅限 CAMERA_DEVICE_API_VERSION_3_0：

重設 HAL 相機裝置處理管道，並設定新的輸入和輸出串流。這項呼叫會將任何現有的串流設定，替換為 stream_list 中定義的串流。在使用 process_capture_request() 提交要求之前，系統會在 initialize() 之後至少呼叫這個方法一次。

stream_list 至少必須包含一個可輸出的串流，且不得包含多個可輸入的串流。

stream_list 可能包含目前處於活動狀態的串流集合 (來自先前呼叫的 configure_stream())。這些串流會已具有有效的使用量、max_buffers 和私人指標值。

如果這類串流已註冊緩衝區，系統就不會再次為該串流呼叫 register_stream_buffers() ，且串流中的緩衝區可立即納入輸入要求。

如果 HAL 需要因新設定而變更現有串流的串流設定，可能會在設定呼叫期間重寫 usage 和/或 max_buffers 的值。

架構會偵測這類變更，然後重新分配串流緩衝區，並在要求中使用該串流的緩衝區之前，再次呼叫 register_stream_buffers() 。

如果 stream_list 中未包含目前有效的串流，HAL 可以安全地移除對該串流的任何參照。這項資源不會在稍後的設定() 呼叫中由架構重複使用，且在 configure_streams() 呼叫傳回後，所有 gralloc 緩衝區都會釋放。

stream_list 結構體由架構擁有，且在這個呼叫完成後可能無法存取。個別 camera3_stream_t 結構體的地址會一直有效，直到第一個 configure_stream() 呼叫結束為止，屆時 stream_list 引數中將不再包含該 camera3_stream_t。HAL 不得變更私人指標以外的串流結構體值，但在 configure_streams() 本身呼叫期間，使用量和 max_buffers 成員除外。

如果是新的串流，串流結構體的使用率、max_buffer 和私人指標欄位都會設為 0。HAL 裝置必須在 configure_streams() 呼叫傳回之前設定這些欄位。這些欄位會由架構和平台 gralloc 模組使用，為每個串流分配 gralloc 緩衝區。

在這種新串流可將緩衝區納入擷取要求之前，架構會使用該串流呼叫 register_stream_buffers() 。不過，在提交要求之前，框架並不需要為 所有 串流註冊緩衝區。這可讓您快速啟動預覽串流 (例如)，並同時或稍後分配其他串流。

---

僅限 CAMERA_DEVICE_API_VERSION_3_1：

重設 HAL 相機裝置處理管道，並設定新的輸入和輸出串流。這項呼叫會將任何現有的串流設定，替換為 stream_list 中定義的串流。在使用 process_capture_request() 提交要求之前，系統會在 initialize() 之後至少呼叫這個方法一次。

stream_list 至少必須包含一個可輸出的串流，且不得包含多個可輸入的串流。

stream_list 可能包含目前處於活動狀態的串流集合 (來自先前呼叫的 configure_stream())。這些串流會已具有有效的使用量、max_buffers 和私人指標值。

如果這類串流已註冊緩衝區，系統就不會再次為該串流呼叫 register_stream_buffers() ，且串流中的緩衝區可立即納入輸入要求。

如果 HAL 需要因新設定而變更現有串流的串流設定，可能會在設定呼叫期間重寫 usage 和/或 max_buffers 的值。

架構會偵測這類變更，然後重新分配串流緩衝區，並在要求中使用該串流的緩衝區之前，再次呼叫 register_stream_buffers() 。

如果 stream_list 中未包含目前有效的串流，HAL 可以安全地移除對該串流的任何參照。這項資源不會在稍後的設定() 呼叫中由架構重複使用，且在 configure_streams() 呼叫傳回後，所有 gralloc 緩衝區都會釋放。

stream_list 結構體由架構擁有，且在這個呼叫完成後可能無法存取。個別 camera3_stream_t 結構體的地址會一直有效，直到第一個 configure_stream() 呼叫結束為止，屆時 stream_list 引數中將不再包含該 camera3_stream_t。除了 configure_streams() 本身呼叫期間的用量和 max_buffers 成員外，HAL 不得變更私人指標以外的串流結構體值。

如果是新的串流，則串流結構體的 max_buffer 和私人指標欄位都會設為 0。使用情形會設為消費者用途標記。HAL 裝置必須在 configure_streams() 呼叫傳回之前設定這些欄位。這些欄位會由架構和平台 gralloc 模組使用，為每個串流分配 gralloc 緩衝區。

在這種新串流可將緩衝區納入擷取要求之前，架構會使用該串流呼叫 register_stream_buffers() 。不過，在提交要求之前，框架並不需要為 所有 串流註冊緩衝區。這可讓您快速啟動預覽串流 (例如)，並同時或稍後分配其他串流。

---

>= CAMERA_DEVICE_API_VERSION_3_2:

重設 HAL 相機裝置處理管道，並設定新的輸入和輸出串流。這項呼叫會將任何現有的串流設定，替換為 stream_list 中定義的串流。在使用 process_capture_request() 提交要求之前，系統會在 initialize() 之後至少呼叫這個方法一次。

stream_list 至少必須包含一個可輸出的串流，且不得包含多個可輸入的串流。

stream_list 可能包含目前處於活動狀態的串流集合 (來自先前呼叫的 configure_stream())。這些串流會已具有有效的使用量、max_buffers 和私人指標值。

如果 HAL 需要因新設定而變更現有串流的串流設定，可能會在設定呼叫期間重寫 usage 和/或 max_buffers 的值。

架構會偵測這類變更，並在使用要求中來自該串流的緩衝區之前，重新分配串流緩衝區。

如果 stream_list 中未包含目前有效的串流，HAL 可以安全地移除對該串流的任何參照。這項資源不會在稍後的設定() 呼叫中由架構重複使用，且在 configure_streams() 呼叫傳回後，所有 gralloc 緩衝區都會釋放。

stream_list 結構體由架構擁有，且在這個呼叫完成後可能無法存取。個別 camera3_stream_t 結構體的地址會一直有效，直到第一個 configure_stream() 呼叫結束為止，屆時 stream_list 引數中將不再包含該 camera3_stream_t。HAL 不得變更私人指標以外的串流結構體值，但在 configure_streams() 本身呼叫期間，使用量和 max_buffers 成員除外。

如果是新的串流，則串流結構體的 max_buffer 和私人指標欄位都會設為 0。使用情形會設為消費者用途標記。HAL 裝置必須在 configure_streams() 呼叫傳回之前設定這些欄位。這些欄位會由架構和平台 gralloc 模組使用，為每個串流分配 gralloc 緩衝區。

架構隨時可能會在擷取要求中加入新分配的緩衝區。一旦 gralloc 緩衝區透過 process_capture_result 傳回至架構 (且已發出相應的 release_fence)，架構隨時都可以釋放或重複使用該緩衝區。

---

先決條件：

只有在沒有任何擷取畫面正在處理時，架構才會呼叫此方法。也就是說，所有結果都已傳回至架構，所有正在處理中的輸入和輸出緩衝區都已傳回，且 HAL 已發出釋放同步區隔的信號。在 configure_streams() 呼叫進行期間，架構不會提交新的擷取要求。

後置條件：

根據相機裝置的靜態中繼資料所記錄的輸出串流大小和格式，HAL 裝置必須自行調整設定，以提供盡可能高的輸出影格率。

效能需求：

這個呼叫可能需要重型資源，且可能需要數百毫秒才能完成，因為可能需要重設及重新設定影像感應器和相機處理管道。不過，HAL 裝置應盡量縮短重新設定延遲時間，以便在應用程式作業模式變更期間 (例如從靜態影像拍攝切換至錄影)，盡量減少使用者可見的暫停時間。

HAL 應在 500 毫秒內從這個呼叫傳回，且必須在 1000 毫秒內從這個呼叫傳回。

傳回值：

0：成功設定串流

-EINVAL：如果要求的串流設定無效。以下列舉一些無效的串流設定：

• 包含多個可輸入的串流 (INPUT 或 BIDIRECTIONAL)
• 不包含任何可輸出的串流 (OUTPUT 或 BIDIRECTIONAL)
• 包含格式不支援或格式大小不支援的串流。
• 包含特定格式的輸出串流過多。
• 不支援的旋轉設定 (僅適用於版本為 CAMERA_DEVICE_API_VERSION_3_3 以上的裝置)
• 串流大小/格式不符合非一般模式的 camera3_stream_configuration_t->operation_mode 規定，或是 HAL 不支援要求的 operation_mode。(僅適用於版本為 CAMERA_DEVICE_API_VERSION_3_3 以上的裝置)

請注意，提交無效串流設定的架構並非正常運作，因為系統會在設定前檢查串流設定。無效的設定表示架構程式碼中存在錯誤，或是 HAL 的靜態中繼資料與串流的必要條件不相符。

-ENODEV：如果發生重大錯誤且裝置無法運作，在傳回此錯誤後，架構只能成功呼叫 close()。

定義位於檔案 camera3.h 的 2769 行。

construct_default_request_settings:

為標準相機用途建立擷取設定。

裝置必須傳回設定緩衝區，且必須符合要求的用途，也就是必須是 CAMERA3_TEMPLATE_* 列舉之一。必須包含所有要求控制項欄位。

HAL 會保留此結構體的擁有權，但結構體的指標必須在裝置關閉前有效。此呼叫傳回緩衝區後，架構和 HAL 可能不會修改緩衝區。後續對相同範本或其他範本的呼叫可能會傳回相同的緩衝區。

效能需求：

這應該是個非阻斷式呼叫。HAL 應在 1 毫秒內從這個呼叫傳回，且必須在 5 毫秒內從這個呼叫傳回。

傳回值：

有效的中繼資料：在成功建立預設設定緩衝區時。

NULL：發生重大錯誤時。傳回此值後，架構只能成功呼叫 close() 方法。

定義位於檔案 camera3.h 的 2859 行。

dump：

列印攝影機裝置的偵錯狀態。當攝影機服務要求進行偵錯傾印作業時，架構會呼叫此方法。這會發生在使用 dumpsys 工具或擷取錯誤報告時。

傳入的檔案描述元可用於使用 dprintf() 或 write() 編寫偵錯文字。文字應僅採用 ASCII 編碼。

效能需求：

這必須是非阻斷式呼叫。HAL 應在 1 毫秒內從這個呼叫傳回，且必須在 10 毫秒內從這個呼叫傳回。這個呼叫可能會在相機運作期間的任何時刻呼叫，因此必須避免發生死結。使用任何同步處理原始碼 (例如互斥鎖或訊號量) 時，應設定逾時值。

定義位於檔案 camera3.h 的 2971 行。

flush：

在指定裝置上，清除目前處理中擷取的所有內容，以及管道中的所有緩衝區。此架構會使用此方法盡快傾倒所有狀態，以便為 configure_streams() 呼叫做好準備。

不需要成功傳回緩衝區，因此在 flush() 時保留的每個緩衝區 (無論是否已成功填入) 都可能會傳回 CAMERA3_BUFFER_STATUS_ERROR。請注意，只要 HAL 成功填入緩衝區，仍可在這個呼叫期間傳回有效的緩衝區 (CAMERA3_BUFFER_STATUS_OK)。

目前在 HAL 中的所有要求都會盡快傳回。未處理的要求應立即傳回錯誤。應停止所有可中斷的硬體區塊，並等待所有不可中斷的區塊。

flush() 可能會與 process_capture_request() 同時呼叫，預期 process_capture_request 會快速傳回，且在該 process_capture_request 呼叫中提交的要求會與所有其他執行中的要求一樣受到處理。由於並行問題，從 HAL 的角度來看，可能會在已叫用但尚未傳回的清除後，啟動 process_capture_request() 呼叫。如果這類呼叫發生在 flush() 傳回之前，HAL 應將新擷取要求視為其他執行中的待處理要求 (請參閱下方的 #4)。

具體來說，HAL 必須遵循以下各種情況的規定：

1. 對於 HAL 無法取消/停止的擷取作業，HAL 會正常完成作業，也就是說，HAL 可以正常傳送快門/通知，並處理_capture_result 和緩衝區。
2. 如果待處理的要求尚未進行任何處理，HAL 就必須呼叫 notify CAMERA3_MSG_ERROR_REQUEST，並傳回所有輸出緩衝區，其中 process_capture_result 處於錯誤狀態 (CAMERA3_BUFFER_STATUS_ERROR)。HAL 不得將釋放柵欄置於錯誤狀態，而是必須將釋放柵欄設為架構傳遞的取得柵欄，如果 HAL 已等待柵欄，則設為 -1。對於 HAL 已使用 CAMERA3_MSG_SHUTTER 呼叫 notify()，但不會產生任何中繼資料/有效緩衝區的任何擷取作業，也必須遵循這個路徑。在 CAMERA3_MSG_ERROR_REQUEST 之後，對於特定影格，只允許 process_capture_results 使用 CAMERA3_BUFFER_STATUS_ERROR 中的緩衝區。不允許使用非空值中繼資料的其他通知或 process_capture_result。

3. 如果部分完成的待處理要求沒有所有輸出緩衝區，或可能缺少中繼資料，HAL 應遵循以下步驟：

   3.1. 如果某些預期的結果中繼資料 (即一或多個部分中繼資料) 無法用於擷取，請呼叫 notify 並傳送 CAMERA3_MSG_ERROR_RESULT。

   3.2. 針對每個不會用於擷取的緩衝區，呼叫通知並使用 CAMERA3_MSG_ERROR_BUFFER。

   3.3 在使用 process_capture_result 傳回任何緩衝區/中繼資料之前，請使用 CAMERA3_MSG_SHUTTER 呼叫通知，並附上擷取時間戳記。

   3.4 如果擷取作業會產生部分結果，HAL 不得呼叫 CAMERA3_MSG_ERROR_REQUEST，因為這表示完全失敗。

   3.5. 有效的緩衝區/中繼資料應正常傳遞至架構。

   3.6. 失敗的緩衝區應依照第 2 種情況所述，傳回至架構。但失敗的緩衝區不必遵循有效緩衝區的嚴格排序，且可能與有效緩衝區的順序不符。舉例來說，如果傳送緩衝區 A、B、C、D、E，且 D 和 E 失敗，則 A、E、B、D、C 是可接受的傳回順序。

   3.7. 如果完全缺少中繼資料，呼叫 CAMERA3_MSG_ERROR_RESULT 即可，不必使用空值中繼資料或等價項目呼叫 process_capture_result。

4. 如果在 process_capture_request() 叫用處於作用中狀態時，呼叫 flush() ，則該程序呼叫應盡快傳回。此外，如果在 flush() 呼叫後，但在 flush() 回傳之前，發出 process_capture_request() 呼叫，則應將由遲發 process_capture_request 呼叫提供的擷取要求，視為上述第 2 種情況中的待處理要求。

flush() 應只在 HAL 中沒有未完成的緩衝區或要求時才傳回。架構可能會呼叫 configure_streams (因為 HAL 狀態現在處於靜默狀態)，或可能會發出新要求。

請注意，只支援完全成功和完全失敗的結果案例就足夠了。不過，建議您也支援部分失敗情況，因為這有助於提升刷新呼叫的整體效能。

效能需求：

HAL 應在 100 毫秒內從這個呼叫傳回，且必須在 1000 毫秒內從這個呼叫傳回。且此呼叫的封鎖時間不得超過管道延遲時間 (請參閱 S7 瞭解定義)。

版本資訊：

僅適用於裝置版本為 CAMERA_DEVICE_API_VERSION_3_1 以上版本。

傳回值：

0：成功刷新相機 HAL。

-EINVAL：如果輸入格式錯誤 (裝置無效)。

-ENODEV：如果相機裝置發生嚴重錯誤。傳回此錯誤後，只有 close() 方法才能成功呼叫架構。

定義位於檔案 camera3.h 的 3077 行。

get_metadata_vendor_tag_ops:

取得查詢供應商擴充功能中繼資料標記資訊的方法。HAL 應填入所有供應商標記作業方法，如果未定義供應商標記，則作業會保持不變。

您可以在 system/media/camera/include/system/camera_metadata.h 中找到 vendor_tag_query_ops_t 的定義。

>= CAMERA_DEVICE_API_VERSION_3_2：已淘汰。這個函式已淘汰，應由 HAL 設為 NULL。請改為在 camera_common.h 中實作 get_vendor_tag_ops。

定義位於檔案 camera3.h 的 2950 行。

initialize：

一次性初始化，將架構回呼函式指標傳遞至 HAL。在成功呼叫 open() 後，系統會先呼叫一次這個函式，然後再呼叫 camera3_device_ops 結構體的任何其他函式。

效能需求：

這應該是個非阻斷式呼叫。HAL 應在 5 毫秒內從這個呼叫傳回，且必須在 10 毫秒內從這個呼叫傳回。

傳回值：

0：初始化成功時

-ENODEV：如果初始化失敗。此後，只有 close() 可以成功呼叫架構。

定義位於檔案 camera3.h 的 2530 行。

process_capture_request：

將新的擷取要求傳送至 HAL。HAL 應在準備好接受下一個要處理的要求前，才會從這個呼叫傳回。架構一次只會呼叫一次 process_capture_request() ，且所有呼叫都會來自同一個執行緒。只要有新要求和相關聯的緩衝區可用，系統就會再次呼叫 process_capture_request() 。在一般預覽情境中，這表示架構幾乎會立即再次呼叫函式。

實際的要求處理程序是非同步的，擷取結果會透過 process_capture_result() 呼叫由 HAL 傳回。這個呼叫需要提供結果中繼資料，但輸出緩衝區可能只提供等待的同步化圍欄。系統會同時執行多個要求，以維持完整的輸出影格速率。

架構會保留要求結構體的擁有權。這個值只保證在這個呼叫期間有效。HAL 裝置必須為擷取作業保留所需資訊的副本。HAL 負責等待並關閉緩衝區的柵欄，並將緩衝區句柄傳回至架構。

如果 input_buffer 不是空值，HAL 就必須將輸入緩衝區的釋放同步化圍欄的檔案描述項寫入 input_buffer->release_fence。如果 HAL 針對輸入緩衝區釋放同步化圍欄傳回 -1，架構就能立即重複使用輸入緩衝區。否則，架構會等待同步區域，然後再重新填充並重複使用輸入緩衝區。

>= CAMERA_DEVICE_API_VERSION_3_2:

在每個要求中，架構提供的輸入/輸出緩衝區可能為全新 (從未在 HAL 中出現過)。

---

效能考量事項：

處理新緩衝區的作業應極為輕量，且不應導致影格速率降低或影格抖動。

這個呼叫必須快速傳回，確保可維持要求的幀率，尤其是在串流播放情況下 (後製品質設定設為「快速」)。HAL 應在 1 個影格間隔內傳回此呼叫，且必須在 4 個影格間隔內從此呼叫傳回。

傳回值：

0：開始處理擷取要求時

-EINVAL：如果輸入內容格式不正確 (設定為 NULL 時不允許，輸出緩衝區為 0 等)，則無法開始擷取處理作業。在要求處理期間發生的失敗，應透過呼叫 camera3_callback_ops_t.notify() 來處理。發生這類錯誤時，架構會保留串流緩衝區的柵欄和緩衝區句柄；HAL 不應關閉柵欄，也不應透過 process_capture_result 傳回這些緩衝區。

-ENODEV：如果相機裝置發生嚴重錯誤。傳回此錯誤後，只有 close() 方法才能成功呼叫架構。

定義位於檔案 camera3.h 的 2928 行。

register_stream_buffers:

>= CAMERA_DEVICE_API_VERSION_3_2:

已淘汰。系統不會呼叫這個值，且必須設為 NULL。

<= CAMERA_DEVICE_API_VERSION_3_1:

使用 HAL 裝置為特定串流註冊緩衝區。在 configure_streams 定義新串流後，這個方法會在擷取要求中加入該串流的緩衝區之前，由架構呼叫。如果後續的 configure_streams() 呼叫列出相同的串流，則 register_stream_buffers 不會再次針對該串流呼叫。

在提交第一個擷取要求之前，架構不需要為所有已設定的串流註冊緩衝區。這樣一來，您就能在其他串流仍在分配的情況下，快速啟動預覽 (或類似用途)。

這個方法可讓 HAL 裝置對應或以其他方式準備緩衝區，以供日後使用。傳入的緩衝區已鎖定供使用。在呼叫結束時，所有緩衝區都必須準備好傳回串流。buffer_set 引數僅在這個呼叫期間有效。

如果串流格式已設為 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED，相機 HAL 應在此檢查傳入的緩衝區，以判斷任何平台專屬的像素格式資訊。

效能需求：

這應該是個非阻斷式呼叫。HAL 應在 1 毫秒內從這個呼叫傳回，且必須在 5 毫秒內從這個呼叫傳回。

傳回值：

0：成功註冊新串流緩衝區

-EINVAL：如果 stream_buffer_set 未參照有效的活動串流，或緩衝區陣列無效。

-ENOMEM：註冊緩衝區失敗。架構必須考慮所有未註冊的串流緩衝區，並可稍後再嘗試註冊。

-ENODEV：如果發生致命錯誤，且裝置無法再運作。在傳回此錯誤後，架構只能成功呼叫 close()。

定義位於檔案 camera3.h 的 2823 行。

定義位於檔案 camera3.h 的第 3080 行。