fuchsia.camera3

新增日期：7

通訊協定

裝置

如 fuchsia.camera3/device.fidl 中定義

裝置代表系統中獨一無二的實體相機。但只有一個用戶端可以連線至未繫結的實體攝影機，但「重新繫結」方法可用來建立多個連線，供一組協調的用戶端使用。

ConnectToStream

在提供的索引連線至串流。如果此串流已有任何用戶端，則要求會以 ZX_ERR_ALREADY_BOUND 基元關閉。

要求

名稱類型
index uint32
request server_end<Stream>

GetConfigurations

傳回相機支援的設定清單。所有相機都會有至少一項設定。傳回的值不可變動，且不會在用戶端與相機連線的生命週期期間變更。

已淘汰 - 使用 GetConfigurations2

要求

<EMPTY>

回應

名稱類型
configurations vector<Configuration>[256]

GetConfigurations2

傳回相機支援的設定清單。所有相機都會有至少一項設定。傳回的值不可變動，且不會在用戶端與相機連線的生命週期期間變更。

要求

<EMPTY>

回應

名稱類型
configurations vector<Configuration2>[256]

GetIdentifier

傳回相機的 ID。如果有的話，不同系統上的相同裝置將具有相同的 ID。用戶端可透過這項功能，判斷特定裝置的已知前級條件是否適用於目前的相機。

要求

<EMPTY>

回應

名稱類型
identifier string[256]?

重新繫結

要求與這部裝置建立其他連線。這可讓用戶端將不同的作業委派給不同的協調用戶端。

要求

名稱類型
request server_end<Device>

SetCurrentConfiguration

使用提供的索引進行設定。呼叫這個方法會中斷與此攝影機相關聯的所有現有串流用戶端。系統會在關閉時，為所有已連結的串流用戶端傳送 ZX_OK 風險。

要求

名稱類型
index uint32

SetSoftwareMuteState

設定目前相機的軟體靜音狀態。轉換至靜音狀態時，如果相機已成功停止傳送新影格給串流用戶端，此方法就會傳回此方法。轉為取消靜音的狀態時，此方法會立即傳回。

要求

名稱類型
muted bool

回應

<EMPTY>

WatchCurrentConfiguration

從先前傳回的設定變更目前設定的索引，或用戶端第一次呼叫時，傳回目前設定的索引。

要求

<EMPTY>

回應

名稱類型
index uint32

WatchMuteState

如果攝影機已從先前傳回的狀態變更，或是由用戶端第一次呼叫，則傳回攝影機目前的靜音狀態。相機可以使用 SetSoftwareMuteState 或實體開關設為靜音。如果任一靜音模式處於靜音模式，與此實體相機相關聯的串流用戶端就會停止接收新影格。

要求

<EMPTY>

回應

名稱類型
software_muted bool
hardware_muted bool

DeviceWatcher

在 fuchsia.camera3/device_watcher.fidl 中定義

DeviceWatcher 可提供用戶端機制，用於探索系統上顯示的相機裝置。這是暫時的機制，旨在由 go/drivers-as-components 取代，這可讓相同通訊協定的多個執行個體並排存在。用戶端不需要與監看員保持連線，就能使用已建立的相機連線。

ConnectToDevice

為指定 ID 取得相機介面。如果這部攝影機已有任何用戶端，則要求會隨 ZX_ERR_ALREADY_BOUND 基元關閉。

要求

名稱類型
id DeviceId
request server_end<Device>

WatchDevices

當物件 ID 從先前傳回的 ID 清單變更，或於用戶端首次呼叫時，傳回可用的相機 ID 清單。傳回的清單可能空白，表示沒有可用的相機。在用戶端連線期間，傳回給用戶端的 ID 會與所代表的實體裝置保持一致。事件會依照事件類型排序：existing、added、removed。在每個事件類型範圍內，系統會按遞增順序提供 ID。伺服器會將事件匯總，因此特定 ID 在每個事件清單中只會顯示一次。

請注意，即使本機相機硬體採用有線電源 (而非 USB 等外掛程式)，回傳清單也完全有可能暫時空白。空白清單條件在該平台上是暫時性的。

相機應用程式應能容許傳回的空白清單，並嘗試重試 WatchDevices() 呼叫。

要求

<EMPTY>

回應

名稱類型
events vector<WatchDevicesEvent>[256]

湖水綠

定義於 fuchsia.camera3/stream.fidl

串流代表套用至緩衝區集合的時間、序列和其他相機專屬屬性。

GetNextFrame

請參閱 GetNextFrame2。

已淘汰 - 使用 GetNextFrame2

要求

<EMPTY>

回應

名稱類型
info FrameInfo

GetNextFrame2

針對這個串流，要求目前用戶端尚未取得的下一個可用影格。多位參與的用戶端可以同時容納同一個影格。當串流完成填入緩衝區，且可由用戶端讀取時，就會傳回此訊息，前提是未發布的緩衝區數量少於透過最近協商的緩衝區收集權杖提供的計數。如果緩衝區重新協商正在進行，則只有在協商完成並有新的集合之後，才會傳回此呼叫。

要求

<EMPTY>

回應

名稱類型
info FrameInfo2

GetProperties

取得與這個串流相關聯的屬性。傳回的值會與 |Device.GetConfigurations| 傳回的值與此串流相對應。

已淘汰 - 使用 GetProperties2

要求

<EMPTY>

回應

名稱類型
properties StreamProperties

GetProperties2

取得與這個串流相關聯的屬性。傳回的值會與 |Device.GetConfigurations| 傳回的值與此串流相對應。

要求

<EMPTY>

回應

名稱類型
properties StreamProperties2

重新繫結

要求與這個直播有關的其他連線。這可讓用戶端將不同的作業委派給不同的協調用戶端，或讓多個用戶端並行觀察串流產生的影格。

要求

名稱類型
request server_end<Stream>

SetBufferCollection

如果非空值，則要求重新交涉這個串流的緩衝區收集作業，並將此用戶端識別為緩衝區協商的參與者。如果為空值，請將這個用戶端標示為不在緩衝區協商中的非參與者。初始連線時，用戶端並非參與者。註冊成為參與者後，用戶端必須讓 WatchBufferCollection 持續呼叫才能接收來自伺服器的憑證，以便回應目前和未來的重新協商要求。

要求

名稱類型
token fuchsia.sysmem/BufferCollectionToken?

SetCropRegion

將串流的裁剪區域設為提供的區域，圖片左上角代表 (0,0)，其右下方以 (1,1) 表示。結果內容隨後會縮放，以填滿輸出緩衝區。如果實作項目無法準確支援提供的值，則會擴大至涵蓋指定區域的最低區域。如果將區域設為空值，系統就不會設定裁剪區域，相當於指定涵蓋整張圖片的區域。初次連線時，系統不會設定該地區。如果串流不支援裁剪區域，則會以 ZX_ERR_NOT_SUPPORTED 心弦關閉連線。

要求

名稱類型
region fuchsia.math/RectF?

SetResolution

將串流的解析度設為提供的值。如果實作方法未準確支援提供的值，則會擴大至超過指定解析度的最低解析度。

要求

名稱類型
coded_size fuchsia.math/Size

WatchBufferCollection

當伺服器或任何緩衝區交涉參與者 (包括目前的用戶端) 需要重新協商，且目前用戶端已註冊為參與者時，就會傳回此值。收到此回呼後收到的影格回呼會套用至新協商的集合。

由於相機可以直接輸出到這些集合，因此每個用戶端都應支援從 RAM 的 |fuchsia.sysmem.CoherencyDomain| 讀取，並在 |fuchsia.sysmem.BufferMemoryConstraints| 中設定 |ram_domain_supported|。

要求

<EMPTY>

回應

名稱類型
token fuchsia.sysmem/BufferCollectionToken

WatchCropRegion

如果裁剪區域已從先前傳回的值變更，或由用戶端首次呼叫，則傳回裁剪區域。收到此回呼後收到的影格回呼會反映新區域的使用情況。如需區域參數的說明，請參閱 SetCropRegion。

要求

<EMPTY>

回應

名稱類型
region fuchsia.math/RectF?

WatchOrientation

如果值已從先前傳回的值變更，或由用戶端首次呼叫，則傳回方向。收到此回呼後，收到的影格回呼會反映新的方向。

要求

<EMPTY>

回應

名稱類型
orientation Orientation

WatchResolution

如果解析度已從先前傳回的值變更，或由用戶端首次呼叫，則傳回解析度。收到此回呼後，收到的影格回呼會反映新的解析度。

要求

<EMPTY>

回應

名稱類型
coded_size fuchsia.math/Size

結構化

設定

如 fuchsia.camera3/device.fidl 中定義

說明相機的獨特設定。

欄位類型說明預設
streams vector<StreamProperties>[256]

說明設定中並行提供的串流說明。

 無預設

FrameInfo 資源

定義於 fuchsia.camera3/stream.fidl

與指定影格相關的中繼資料。

欄位類型說明預設
buffer_index uint32

找出此影格使用的緩衝區，做為最近協商的緩衝區集合中的索引。

 無預設
frame_counter uint64

單純遞增的計數器，顯示寫入這個串流最近剛協商緩衝區集合的影格數量。用戶端可利用這項功能偵測遺失的影格，或利用關聯串流的影格速率產生名目時間戳記。

 無預設
timestamp zx/Time

系統單調時鐘的值，在硬體完成填入緩衝區時開始測量。

 無預設
release_fence handle<eventpair>

一旦用戶端完成讀取緩衝區的作業，用戶端就必須關閉此事件。

 無預設

FrameRate

定義於 fuchsia.camera3/stream.fidl

串流產生影格的頻率。這個值是 numerator / denominator，採用每秒影格數 (Hz)。而表示不一定是無法避免的分數。

欄位類型說明預設
numerator uint32

分數分子。

 無預設
denominator uint32

分數分母。這個值不得為 0。

 無預設

StreamProperties

定義於 fuchsia.camera3/stream.fidl

說明指定串流的屬性。

欄位類型說明預設
image_format fuchsia.sysmem/ImageFormat_2

說明串流使用的原生圖片格式。

 無預設
frame_rate FrameRate

說明串流使用的影格速率。

 無預設
supports_crop_region bool

指出串流是否支援 SetCropRegion 方法。

 無預設

ENUMS

螢幕方向嚴格

類型：uint32

定義於 fuchsia.camera3/stream.fidl

說明特定串流相對於其編碼資料的預期方向。為求明確，每個列舉值的說明文件都附帶一個圓圈「⮬」符號，用於說明串流編碼資料的方向。

名稱值說明
1

⮬：內容已正確方向。
2

⮯：內容必須旋轉 180 度才能正確顯示。
3

⮫：內容必須向左旋轉 90 度 (逆時針方向)，才能正確顯示。
4

⮨：內容必須向右旋轉 90 度 (順時針方向) 才能正確顯示。
5

⮭：內容必須水平翻轉才能正確顯示。
6

⮮：內容必須水平翻轉，然後旋轉 180 度才能正確顯示。
7

⮪：內容必須水平翻轉，然後向左旋轉 90 度 (逆時針) 才能正確顯示。
8

⮩：內容必須水平翻轉，然後向右旋轉 90 度 (順時針方向)，內容才能正確顯示。

資料表

Configuration2

如 fuchsia.camera3/device.fidl 中定義

說明相機的獨特設定。

序數欄位類型說明
streams vector<StreamProperties2>[256]

說明設定中並行提供的串流說明。

FrameInfo2 資源

定義於 fuchsia.camera3/stream.fidl

與指定影格相關的中繼資料。

序數欄位類型說明
buffer_index uint32

找出此影格使用的緩衝區，做為最近協商的緩衝區集合中的索引。
frame_counter uint64

單純遞增的計數器，顯示寫入這個串流最近剛協商緩衝區集合的影格數量。用戶端可利用這項功能偵測遺失的影格，或利用關聯串流的影格速率產生名目時間戳記。
timestamp zx/Time

系統單調時鐘的值，在硬體完成填入緩衝區時開始測量。
capture_timestamp zx/Time

系統單調時鐘的值，在硬體完成填入原始緩衝區後所得，在此緩衝區內產生內容的時間開始測量。
release_fence handle<eventpair>

一旦用戶端完成讀取緩衝區的作業，用戶端就必須關閉此事件。

StreamProperties2

定義於 fuchsia.camera3/stream.fidl

說明指定串流的屬性。

序數欄位類型說明
image_format fuchsia.sysmem/ImageFormat_2

說明串流使用的原生圖片格式。
frame_rate FrameRate

說明串流使用的影格速率。
supports_crop_region bool

指出串流是否支援 SetCropRegion 方法。
supported_resolutions vector<fuchsia.math/Size>[256]

說明串流支援的精確解析度，亦即，SetResolution 回呼會產生相同值的 WatchResolution 回呼。如果空白，表示串流支援任意解析度。如果非空白，清單至少會包含一個元素，反映 |image_format| 指定的原生解析度。

聯合國

Watch DevicesEvent 嚴格

在 fuchsia.camera3/device_watcher.fidl 中定義

序數Variant類型說明
existing DeviceId

表示提供的現有相機仍可使用提供的 ID。
added DeviceId

表示具有所提供 ID 的新相機現已可供使用。
removed DeviceId

表示使用該 ID 的現有相機已無法使用。

業者

名稱值類型說明
MAX_CONFIGURATIONS_PER_CAMERA 256 uint32
MAX_IDENTIFIER_LENGTH 256 uint32
MAX_RESOLUTIONS_PER_STREAM 256 uint32
MAX_STREAMS_PER_CONFIGURATION 256 uint32
MAX_WATCH_DEVICES_EVENTS 256 uint32

別名

名稱值說明
DeviceId uint64