#include < camera3.h >

資料欄位
整數（*	初始化)(const structcamera3_device , constcamera3_callback_ops_t callback_ops)

整數（*	配置_流）（常數結構camera3_device ， camera3_stream_configuration_t stream_list）

整數（*	register_stream_buffers ）（const structcamera3_device ， constcamera3_stream_buffer_set_t buffer_set）

常數camera_metadata_t (	Construction_default_request_settings ）（const structcamera3_device *，int型別）

整數（*	process_capture_request ）（常數結構camera3_device ， camera3_capture_request_t 請求）

空白（*	get_metadata_vendor_tag_ops ）（const structcamera3_device ，vendor_tag_query_ops_t ops）

空白（*	轉儲）（常數結構camera3_device *，int fd）

整數（*	沖洗）（常量結構camera3_device *）

空白 *	保留[8]

詳細說明

檔案camera3.h第2509行的定義。

現場文檔

int(*configure_streams)( conststructcamera3_device *, camera3_stream_configuration_t *stream_list)

配置流程：

僅限 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 由於新配置而需要更改現有流的流配置，則它可能會在配置呼叫期間重寫 use 和/或 max_buffers 的值。

框架將偵測到此類更改，然後重新分配流緩衝區，並在請求中使用該流中的緩衝區之前再次呼叫register_stream_buffers() 。

如果目前活動的流未包含在stream_list中，則HAL可以安全地刪除對該流的任何引用。框架不會在以後的 configure() 呼叫中重複使用它，並且在configure_streams()呼叫返回後，它的所有 gralloc 緩衝區都會被釋放。

Stream_list 結構由框架擁有，一旦此呼叫完成，就可能無法存取。單一camera3_stream_t結構的位址將保持有效以供HAL訪問，直到第一個configure_stream()呼叫結束，該呼叫不再在stream_list參數中包含該camera3_stream_t。 HAL 不能更改私有指標之外的流結構中的值，除了在configure_streams()呼叫本身期間的usage 和max_buffers 成員。

如果流是新的，則流結構的usage、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 由於新配置而需要更改現有流的流配置，則它可能會在配置呼叫期間重寫 use 和/或 max_buffers 的值。

框架將偵測到此類更改，然後重新分配流緩衝區，並在請求中使用該流中的緩衝區之前再次呼叫register_stream_buffers() 。

如果目前活動的流未包含在stream_list中，則HAL可以安全地刪除對該流的任何引用。框架不會在以後的 configure() 呼叫中重複使用它，並且在configure_streams()呼叫返回後，它的所有 gralloc 緩衝區都會被釋放。

Stream_list 結構由框架擁有，一旦此呼叫完成，就可能無法存取。單一camera3_stream_t結構的位址將保持有效以供HAL訪問，直到第一個configure_stream()呼叫結束，該呼叫不再在stream_list參數中包含該camera3_stream_t。 HAL 不能更改私有指標之外的流結構中的值，除了在configure_streams()呼叫本身期間的usage 和max_buffers 成員。

如果流是新的，則流結構的 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 由於新配置而需要更改現有流的流配置，則它可能會在配置呼叫期間重寫 use 和/或 max_buffers 的值。

框架將檢測此類更改，然後可能會在請求中使用該流中的緩衝區之前重新分配流緩衝區。

如果目前活動的流未包含在stream_list中，則HAL可以安全地刪除對該流的任何引用。框架不會在以後的 configure() 呼叫中重複使用它，並且在configure_streams()呼叫返回後，它的所有 gralloc 緩衝區都會被釋放。

Stream_list 結構由框架擁有，一旦此呼叫完成，就可能無法存取。單一camera3_stream_t結構的位址將保持有效以供HAL訪問，直到第一個configure_stream()呼叫結束，該呼叫不再在stream_list參數中包含該camera3_stream_t。 HAL 不能更改私有指標之外的流結構中的值，除了在configure_streams()呼叫本身期間的usage 和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：如果請求的流配置無效。無效流配置的一些範例包括：

包括超過 1 個可輸入的串流（INPUT 或 BIDIRECTIONAL）
不包括任何可輸出的流（輸出或雙向）
包括格式不受支援的流，或該格式的大小不受支援。
包括太多某種格式的輸出流。
不支援的旋轉配置（僅適用於版本 >= CAMERA_DEVICE_API_VERSION_3_3 的裝置）
串流大小/格式不符合非正常模式的camera3_stream_configuration_t->操作模式要求，或HAL不支援請求的操作模式。（僅適用於版本 >= CAMERA_DEVICE_API_VERSION_3_3 的裝置）

請注意，提交無效流配置的框架不是正常操作，因為在配置之前會檢查流配置。無效的配置意味著框架程式碼中存在錯誤，或HAL的靜態元資料與流的要求不符。

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

檔案camera3.h第2769行的定義。

constcamera_metadata_t *(*construct_default_request_settings)(const structcamera3_device *, int 類型)

建構預設請求設定：

為標準相機用例建立捕捉設定。

裝置必須傳回一個配置為滿足所請求案例的設定緩衝區，該緩衝區必須是 CAMERA3_TEMPLATE_* 枚舉之一。必須包含所有請求控製字段。

HAL 保留該結構的所有權，但指向該結構的指標必須在裝置關閉之前有效。一旦此呼叫返回緩衝區，框架和 HAL 就不能修改緩衝區。可以為同一模板或其他模板的後續呼叫傳回相同的緩衝區。

性能要求：

這應該是一個非阻塞呼叫。 HAL 應在 1 毫秒內從此呼叫返回，並且必須在 5 毫秒內從此呼叫返回。

傳回值：

有效元資料：成功建立預設設定緩衝區時。

NULL：如果發生致命錯誤。返回後，框架才能成功呼叫close()方法。

檔案camera3.h第2859行的定義。

void(* dump)(const structcamera3_device *, int fd)

傾倒：

列印相機設備的調試狀態。當相機服務被要求進行調試轉儲時（使用 dumpsys 工具或捕獲錯誤報告時會發生這種情況），框架將呼叫此函數。

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

性能要求：

這必須是非阻塞呼叫。 HAL 應在 1 毫秒內從此呼叫返回，必須在 10 毫秒內從此呼叫返回。此呼叫必須避免死鎖，因為它可能在相機操作期間的任何時刻被呼叫。使用的任何同步原語（例如互斥鎖或信號量）都應該在逾時時取得。

檔案camera3.h第2971行的定義。

int(* 刷新)(const structcamera3_device *)

沖洗：

刷新給定設備上所有目前正在處理的捕獲以及管道中的所有緩衝區。框架將使用它盡快轉儲所有狀態，以便為configure_streams()呼叫做好準備。

不需要成功返回緩衝區，因此在flush()時保存的每個緩衝區（無論是否成功填充）都可能會返回CAMERA3_BUFFER_STATUS_ERROR。請注意，在此呼叫期間，HAL 仍然允許傳回有效的 (CAMERA3_BUFFER_STATUS_OK) 緩衝區，前提是它們已成功填入。

當前 HAL 中的所有請求預計都會盡快返回。未處理的請求應立即傳回錯誤。應停止任何可中斷的硬體區塊，並應等待任何不可中斷的區塊。

lush()可以與process_capture_request()同時調用，期望 process_capture_request 將快速返回，並且在 process_capture_request 呼叫中提交的請求將像所有其他正在進行的請求一樣對待。由於並發問題，從 HAL 的角度來看， process_capture_request()呼叫可能會在呼叫 flash 後啟動但尚未傳回。如果這樣的呼叫發生在flush()返回之前，HAL應該像其他正在進行的待處理請求一樣對待新的捕獲請求（請參閱下面的#4）。

更具體地說，HAL 必須針對各種情況遵循以下要求：

對於 HAL 來不及取消/停止的捕獲，將由 HAL 正常完成；即 HAL 可以正常發送快門/通知和 process_capture_result 和緩衝區。
對於尚未完成任何處理的掛起請求，HAL 必須呼叫通知 CAMERA3_MSG_ERROR_REQUEST，並傳回所有 process_capture_result 處於錯誤狀態 (CAMERA3_BUFFER_STATUS_ERROR) 的輸出緩衝區。 HAL 不得將釋放柵欄置於錯誤狀態，相反，釋放柵欄必須設置為框架傳遞的獲取柵欄，如果 HAL 已等待它們，則設置為 -1。對於 HAL 已使用 CAMERA3_MSG_SHUTTER 呼叫 notification() 但不會產生任何元資料/有效緩衝區的任何捕獲，這也是要遵循的路徑。在 CAMERA3_MSG_ERROR_REQUEST 之後，對於給定幀，僅允許使用 CAMERA3_BUFFER_STATUS_ERROR 中的緩衝區的 process_capture_results。不允許進一步使用非空元資料進行通知或 process_capture_result。
對於部分完成的待處理請求，這些請求不會具有所有輸出緩衝區或可能缺少元數據，HAL 應遵循以下步驟：
3.1.如果某些預期結果元資料（即一個或多個部分元資料）不可用於捕獲，請使用 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 就足夠了，而無需使用 NULL 元資料或等效函數呼叫 process_capture_result。
如果在process_capture_request( ) 呼叫處於活動狀態時呼叫了 flash() ，則該程序呼叫應盡快傳回。此外，如果在調用flush()之後但在flush()返回之前進行process_capture_request ()調用，則由後期process_capture_request調用提供的捕獲請求應被視為上述情況#2中的待處理請求。

只有當 HAL 中不再有未完成的緩衝區或請求時，才應將flush()傳回。框架可能會呼叫configure_streams（因為HAL狀態現在已停止）或可能會發出新的請求。

請注意，僅支援完全成功和完全失敗的結果情況就足夠了。然而，非常希望也支援部分失敗情況，因為它可以幫助提高刷新呼叫的整體效能。

性能要求：

HAL 應在 100 毫秒內從此呼叫返回，並且必須在 1000 毫秒內從此呼叫返回。且此呼叫的阻塞時間不得超過管道延遲（請參閱 S7 的定義）。

版本資訊：

僅當裝置版本 >= CAMERA_DEVICE_API_VERSION_3_1 時可用。

傳回值：

0：成功刷新相機 HAL。

-EINVAL：如果輸入格式錯誤（設備無效）。

-ENODEV：如果相機設備遇到嚴重錯誤。傳回此錯誤後，框架只能成功呼叫close()方法。

定義在檔案camera3.h的第3077行。

void(* get_metadata_vendor_tag_ops)(const structcamera3_device *,vendor_tag_query_ops_t *ops)

get_metadata_vendor_tag_ops：

取得查詢供應商擴展元資料標籤資訊的方法。 HAL 應填寫所有供應商標籤操作方法，或如果未定義供應商標籤，則保持操作不變。

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

>= CAMERA_DEVICE_API_VERSION_3_2：已棄用。該函數已被棄用，應由 HAL 設定為 NULL。請改為在camera_common.h中實作get_vendor_tag_ops。

檔案camera3.h第2950行的定義。

int(* 初始化)(const structcamera3_device *, constcamera3_callback_ops_t *callback_ops)

初始化：

一次性初始化，將框架回呼函數指標傳遞給 HAL。將在成功呼叫 open() 後、在camera3_device_ops結構上呼叫任何其他函數之前呼叫一次。

性能要求：

這應該是一個非阻塞呼叫。 HAL 應在 5 毫秒內從此呼叫返回，並且必須在 10 毫秒內從此呼叫返回。

傳回值：

0：初始化成功時

-ENODEV：如果初始化失敗。此後框架只能成功呼叫 close()。

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

int（* process_capture_request）（const structcamera3_device *， camera3_capture_request_t *請求）

處理_捕獲_請求：

向 HAL 發送新的捕獲請求。在準備好接受下一個要處理的請求之前，HAL 不應從此呼叫傳回。框架一次只會呼叫一次process_capture_request() ，且所有呼叫都來自同一線程。一旦新請求及其關聯的緩衝區可用，就會立即呼叫process_capture_request() 。在正常的預覽場景中，這意味著框架幾乎會立即再次呼叫該函數。

實際的請求處理是異步的，捕獲結果由 HAL 透過 process_capture_result() 呼叫傳回。此呼叫要求結果元資料可用，但輸出緩衝區可能只是提供同步柵欄來等待。多個請求預計會同時進行，以保持完整的輸出幀速率。

框架保留請求結構的所有權。僅保證在本次呼叫期間有效。 HAL 設備必須複製擷取處理所需保留的資訊。 HAL 負責等待和關閉緩衝區的柵欄，並將緩衝區句柄傳回框架。

如果 input_buffer 不為 NULL，HAL 必須將輸入緩衝區的釋放同步柵欄的檔案描述符寫入 input_buffer->release_fence。如果 HAL 對於輸入緩衝區釋放同步柵欄返回 -1，則框架可以立即重複使用輸入緩衝區。否則，框架將在重新填充和重複使用輸入緩衝區之前等待同步柵欄。

>= CAMERA_DEVICE_API_VERSION_3_2：

框架在每個請求中提供的輸入/輸出緩衝區可能是全新的（HAL 以前從未見過）。

性能考量：

處理新緩衝區應該非常輕量級，並且不應引入幀速率下降或幀抖動。

此呼叫必須足夠快地返回，以確保可以維持請求的幀速率，特別是對於串流媒體情況（後處理品質設定設定為 FAST）。 HAL 應在 1 幀間隔內返回此調用，並且必須在 4 幀間隔內從此調用返回。

傳回值：

0：成功開始處理捕獲請求

-EINVAL：如果輸入格式錯誤（不允許時設定為 NULL、輸出緩衝區為 0 等）且擷取處理無法啟動。請求處理期間的失敗應透過呼叫camera3_callback_ops_t.notify()來處理。如果發生此錯誤，框架將保留對流緩衝區的柵欄和緩衝區句柄的責任； HAL 不應關閉柵欄或使用 process_capture_result 傳回這些緩衝區。

-ENODEV：如果相機設備遇到嚴重錯誤。傳回此錯誤後，框架只能成功呼叫close()方法。

檔案camera3.h第2928行的定義。

int(* register_stream_buffers)(const structcamera3_device *, constcamera3_stream_buffer_set_t *buffer_set)

註冊流緩衝區：

>= 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_IMPLMENTATION_DEFINED，則相機 HAL 應檢查此處傳入的緩衝區以確定任何平台私有的像素格式資訊。

性能要求：

這應該是一個非阻塞呼叫。 HAL 應在 1 毫秒內從此呼叫返回，並且必須在 5 毫秒內從此呼叫返回。

傳回值：

0：成功註冊新流緩衝區

-EINVAL：如果stream_buffer_set未引用有效的活動流，或緩衝區數組無效。

-ENOMEM：如果註冊緩衝區失敗。框架必須考慮所有流緩衝區都已取消註冊，並且可以稍後嘗試再次註冊。

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

檔案camera3.h第2823行的定義。

無效* 保留[8]

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

該結構的文檔是從以下文件產生的：

硬體/libhardware/include/hardware/camera3.h

camera3_device_ops結構參考

資料欄位

詳細說明

現場文檔