camera3_device_ops結構參考

camera3_device_ops結構參考

#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.h2509行的定義。

現場文檔

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.h2769行的定義。

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

建構預設請求設定:

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

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

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

性能要求:

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

傳回值:

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

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

檔案camera3.h2859行的定義。

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

傾倒:

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

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

性能要求:

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

檔案camera3.h2971行的定義。

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 必須針對各種情況遵循以下要求:

  1. 對於 HAL 來不及取消/停止的捕獲,將由 HAL 正常完成;即 HAL 可以正常發送快門/通知和 process_capture_result 和緩衝區。
  2. 對於尚未完成任何處理的掛起請求,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。
  3. 對於部分完成的待處理請求,這些請求不會具有所有輸出緩衝區或可能缺少元數據,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。

  4. 如果在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.h2950行的定義。

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.h2928行的定義。

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.h2823行的定義。

無效* 保留[8]

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


該結構的文檔是從以下文件產生的:
  • 硬體/libhardware/include/hardware/camera3.h