通訊協定
裝置
定義於 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
使用提供的索引設定。呼叫這個方法會中斷與這部攝影機相關聯的所有現有 Stream 用戶端連線。關閉時，系統會為所有已連線的串流用戶端傳送 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 會與其代表的實體裝置保持一致。事件會先依事件類型排序：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
要求
| 名稱 | 類型 |
|---|---|
token |
client_end:fuchsia.sysmem/BufferCollectionToken?
|
SetBufferCollection2
如果不是空值，則會要求重新協商支援這個串流的緩衝區集合，並將這個用戶端識別為緩衝區協商的參與者。如果為空值，則表示這個用戶端未參與緩衝區協商。初次連線時，用戶端為非參與者。註冊為參與者後，用戶端必須一律對 WatchBufferCollection2 進行未完成的呼叫，才能從伺服器接收權杖，以便回應目前和未來的重新協商要求。
要求
| 名稱 | 類型 |
|---|---|
token |
client_end:fuchsia.sysmem2/BufferCollectionToken?
|
SetCropRegion
將串流的裁剪區域設為指定區域，圖片左上角以 (0,0) 表示，右下角以 (1,1) 表示。接著，系統會縮放產生的內容，填滿輸出緩衝區。如果實作不完全支援提供的值，則會擴展至涵蓋提供區域的最小區域。如果區域設為空值，則不會設定裁剪區域，這相當於指定涵蓋整個圖片的區域。初始連線時，區域未設定。如果串流不支援裁剪區域，連線會關閉，並顯示 ZX_ERR_NOT_SUPPORTED 墓誌銘。
要求
| 名稱 | 類型 |
|---|---|
region |
fuchsia.math/RectF?
|
SetResolution
將串流解析度設為指定值。如果實作方式不完全支援提供的值，則會擴充至超過提供解析度的最小解析度。
要求
| 名稱 | 類型 |
|---|---|
coded_size |
fuchsia.math/Size
|
WatchBufferCollection
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
token |
client_end:fuchsia.sysmem/BufferCollectionToken
|
WatchBufferCollection2
當伺服器或任何緩衝區協商參與者 (包括目前用戶端) 需要重新協商緩衝區，且目前用戶端已註冊為參與者時，就會傳回。收到這個回呼後，收到的影格回呼會套用至新協商的集合。
由於相機可以直接輸出至這些集合，因此每個用戶端都應支援從 RAM 的 |fuchsia.sysmem.CoherencyDomain| 讀取，並在 |fuchsia.sysmem.BufferMemoryConstraints| 中設定 |ram_domain_supported|。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
token |
client_end:fuchsia.sysmem2/BufferCollectionToken
|
WatchCropRegion
如果裁剪區域與先前傳回的值不同，或用戶端首次呼叫，則傳回裁剪區域。收到這個回呼後，收到的影格回呼會反映新區域的使用情形。如需區域參數的說明，請參閱 SetCropRegion。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
region |
fuchsia.math/RectF?
|
WatchOrientation
如果螢幕方向與先前傳回的值不同，或用戶端首次呼叫，則傳回螢幕方向。收到這個回呼後，系統會根據新的螢幕方向接收影格回呼。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
orientation |
Orientation
|
WatchResolution
如果解析度與先前傳回的值不同，或用戶端首次呼叫，則傳回解析度。收到這個回呼後，收到的影格回呼會反映新的解析度。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
coded_size |
fuchsia.math/Size
|
STRUCTS
設定
定義於 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
|
分數分母。這個值不會是零。 |
無預設值 |
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
說明指定串流相對於其編碼資料的預期方向。為求明確，每個列舉值的說明文件都會附上對掌性「⮬」符號的方向，說明串流編碼資料的方向。
| 名稱 | 值 | 說明 |
|---|---|---|
UP |
1 |
⮬：內容方向正確。 |
下 |
2 |
⮯：內容必須旋轉 180 度才能正確顯示。 |
餘額 |
3 |
⮫：內容必須向左 (逆時針) 旋轉 90 度，才能正確顯示。 |
右 |
4 |
⮨：內容必須向右 (順時針) 旋轉 90 度，才能正確顯示。 |
UP_FLIPPED |
5 |
：內容必須水平翻轉，才能正確顯示。 |
DOWN_FLIPPED |
6 |
⮮：內容必須水平翻轉，然後旋轉 180 度，才能正確顯示。 |
LEFT_FLIPPED |
7 |
⮪：內容必須水平翻轉，然後向左旋轉 90 度 (逆時針)，才能正確顯示。 |
RIGHT_FLIPPED |
8 |
⮩：內容必須水平翻轉，然後向右 (順時針) 旋轉 90 度，才能正確顯示。 |
TABLES
Configuration2
定義於 fuchsia.camera3/device.fidl
說明攝影機的獨特設定。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
streams |
vector<StreamProperties2>:256
|
設定中同時可用的串流說明。 |
FrameInfo2 資源
定義於 fuchsia.camera3/stream.fidl
指定影格的中繼資料。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
buffer_index |
uint32
|
將用於這個影格的緩衝區，識別為最近協商的緩衝區集合索引。 |
2 |
frame_counter |
uint64
|
單調遞增計數器，指出寫入這個串流最近協商緩衝區集合的影格數量。用戶端可使用這項資訊偵測影格遺失，或使用相關聯串流的影格速率產生標稱時間戳記。 |
3 |
timestamp |
zx/Time
|
系統單調時鐘的值，在硬體完成填入緩衝區時測量。 |
4 |
capture_timestamp |
zx/Time
|
系統單調時鐘的值，測量時間為硬體完成填入原始緩衝區時，該緩衝區用於衍生此緩衝區的內容。 |
5 |
release_fence |
handle<eventpair>
|
用戶端讀取完緩衝區後，必須關閉這個檔案描述元。 |
StreamProperties2
定義於 fuchsia.camera3/stream.fidl
說明特定串流的屬性。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
image_format |
fuchsia.sysmem/ImageFormat_2
|
說明串流使用的原生圖片格式。 |
2 |
frame_rate |
FrameRate
|
說明串流使用的影格速率。 |
3 |
supports_crop_region |
bool
|
指出串流是否支援 SetCropRegion 方法。 |
4 |
supported_resolutions |
vector<fuchsia.math/Size>:256
|
說明串流支援的精確解析度，也就是 SetResolution 產生相同值的 WatchResolution 回呼。如果留空，表示串流支援任意解析度。如果清單不為空白，則至少包含一個元素，反映 |image_format| 指定的原生解析度。 |
UNIONS
WatchDevicesEvent strict
定義於 fuchsia.camera3/device_watcher.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
existing |
DeviceId
|
表示具有指定 ID 的現有攝影機仍可使用。 |
2 |
added |
DeviceId
|
表示現在可以使用具有指定 ID 的新相機。 |
3 |
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 |