PROTOCOLS
Device
Defined in fuchsia.camera3/device.fidl
A Device represents a unique physical camera present in the system. Only one client may connect to an unbound physical camera, however the "Rebind" method can be used to create multiple connections to it to be used by a coordinated set of clients.
ConnectToStream
Connects to the Stream at the provided index. If any clients already exist for this stream, the request is closed with the ZX_ERR_ALREADY_BOUND epitaph.
Request
| Name | Type |
|---|---|
index |
uint32
|
request |
server_end:Stream
|
GetConfigurations
Returns a list of configurations supported by the camera. All cameras will have at least one configuration. The values returned are immutable - they will not change for the lifetime of the client's connection to the Camera.
DEPRECATED - Use GetConfigurations2
Request
<EMPTY>
Response
| Name | Type |
|---|---|
configurations |
vector<Configuration>:256
|
GetConfigurations2
Returns a list of configurations supported by the camera. All cameras will have at least one configuration. The values returned are immutable - they will not change for the lifetime of the client's connection to the Camera.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
configurations |
vector<Configuration2>:256
|
GetIdentifier
Returns an identifier for the camera. If present, identical devices on different systems will have the same identifier. Clients may use this to determine if additional semantics known a priori for a given device apply to the current camera.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
identifier |
string:256?
|
Rebind
Request another connection to this Device. This allows a client to delegate different operations to different coordinated clients.
Request
| Name | Type |
|---|---|
request |
server_end:Device
|
SetCurrentConfiguration
Sets the configuration using the provided index. Calling this method disconnects any existing Stream clients associated with this camera. An epitaph of ZX_OK will be sent for any connected Stream clients on closing.
Request
| Name | Type |
|---|---|
index |
uint32
|
SetSoftwareMuteState
Sets the current camera's software mute state. When transitioning to the muted state, this method returns when the camera has successfully ceased sending new frames to stream clients. When transitioning to the unmuted state, this method returns immediately.
Request
| Name | Type |
|---|---|
muted |
bool
|
Response
<EMPTY>
WatchCurrentConfiguration
Returns the index of the current configuration when it has changed from a previously returned configuration, or is called by a client for the first time.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
index |
uint32
|
WatchMuteState
Returns the camera's current mute state when it has changed from a previously returned state, or is called by a client for the first time. A camera may be muted using SetSoftwareMuteState or by a physical switch. If either muted mode is active, stream clients associated with this physical camera will stop receiving new frames.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
software_muted |
bool
|
hardware_muted |
bool
|
DeviceWatcher
Defined in fuchsia.camera3/device_watcher.fidl
The DeviceWatcher provides clients a mechanism to discover camera devices present on the system. This is a temporary mechanism intended to be replaced by go/drivers-as-components, which will allow multiple instances of the same protocol to exist side-by-side. Clients are not required to maintain a connection to the Watcher in order to use established Camera connections.
ConnectToDevice
Acquires a camera interface for the given ID. If any clients already exist for this camera, the request is closed with the ZX_ERR_ALREADY_BOUND epitaph.
Request
| Name | Type |
|---|---|
id |
DeviceId
|
request |
server_end:Device
|
WatchDevices
Returns a list of available camera IDs when it has changed from the previously returned
list of IDs, or when it is called by a client for the first time. The returned list may be
empty, indicating no cameras are available. The IDs returned to the client will remain
consistent with respect to the physical devices they represent for the duration of the
client's connection. Events will be sorted first by event type - existing, added,
removed. Within each event type range, IDs will be provided in ascending order. Events
are coalesced by the server, so a given ID will only appear once in each list of events.
Please note that it is entirely possible for the list returned to be temporarily empty even if the local camera hardware is hardwired (vs plug-in like USB). The empty list condition is temporary on such a platform.
Camera applications should tolerate an empty list returned, and attempt to retry the
WatchDevices() call.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
events |
vector<WatchDevicesEvent>:256
|
Stream
Defined in fuchsia.camera3/stream.fidl
A Stream represents timing, sequencing, and other camera-specific properties applied to a buffer collection.
GetNextFrame
See GetNextFrame2.
DEPRECATED - Use GetNextFrame2
Request
<EMPTY>
Response
| Name | Type |
|---|---|
info |
FrameInfo
|
GetNextFrame2
Request the next available frame for this stream that has not yet been acquired by the current client. Multiple participating clients may concurrently hold the same frame. Returns when the stream has completed populating the buffer and may be read by the client, provided the number of unreleased buffers is less than the count provided via the most recently negotiated buffer collection token. If a buffer renegotiation is in progress, this call will return only after the negotiation is complete and a new collection is available.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
info |
FrameInfo2
|
GetProperties
Gets the properties associated with this stream. The value returned is identical to the one corresponding to this stream as returned by |Device.GetConfigurations|.
DEPRECATED - Use GetProperties2
Request
<EMPTY>
Response
| Name | Type |
|---|---|
properties |
StreamProperties
|
GetProperties2
Gets the properties associated with this stream. The value returned is identical to the one corresponding to this stream as returned by |Device.GetConfigurations|.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
properties |
StreamProperties2
|
Rebind
Request another connection to this Stream. This allows a client to delegate different operations to different coordinated clients, or have multiple clients concurrently observe frames produced by the stream.
Request
| Name | Type |
|---|---|
request |
server_end:Stream
|
SetBufferCollection
Request
| Name | Type |
|---|---|
token |
client_end:fuchsia.sysmem/BufferCollectionToken?
|
SetBufferCollection2
If non-null, requests renegotiation of the buffer collection backing this stream, and identifies this client as a participant in buffer negotiation. If null, identifies this client as a non-participant in buffer negotiation. Upon initial connection, the client is a non-participant. After registering as a participant, clients must always have an outstanding call to WatchBufferCollection to receive tokens from the server so that they are able to respond to current and future renegotiation requests.
Request
| Name | Type |
|---|---|
token |
client_end:fuchsia.sysmem2/BufferCollectionToken?
|
SetCropRegion
Sets the Stream's crop region to the provided region, with the top-left of the image represented by (0,0) and the bottom-right of the image represented by (1,1). The resulting content is subsequently scaled to fill the output buffer. If the implementation does not precisely support the provided value, it will be expanded to the minimum region that covers the provided region. If region is set to null, the crop region is unset, which is equivalent to specifying a region covering the entire image. Upon initial connection, the region is unset. If the stream does not support crop region, the connection is closed with the ZX_ERR_NOT_SUPPORTED epitaph.
Request
| Name | Type |
|---|---|
region |
fuchsia.math/RectF?
|
SetResolution
Sets the resolution of the stream to the provided value. If the implementation does not precisely support the provided value, it will be expanded to the minimum resolution that exceeds the provided resolution.
Request
| Name | Type |
|---|---|
coded_size |
fuchsia.math/Size
|
WatchBufferCollection
Request
<EMPTY>
Response
| Name | Type |
|---|---|
token |
client_end:fuchsia.sysmem/BufferCollectionToken
|
WatchBufferCollection2
Returns when the server or any buffer negotiation participant (including the current client) requires buffer renegotiation, and the current client is registered as a participant. Frame callbacks received after receiving this callback apply to the newly negotiated collection.
Because the camera can output directly to these collections, each client should support reading from a |fuchsia.sysmem.CoherencyDomain| of RAM, and set |ram_domain_supported| in their |fuchsia.sysmem.BufferMemoryConstraints|.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
token |
client_end:fuchsia.sysmem2/BufferCollectionToken
|
WatchCropRegion
Returns the crop region if it has changed from a previously returned value, or is called by a client for the first time. Frame callbacks received after receiving this callback reflect the use of the new region. See SetCropRegion for a description of the region parameter.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
region |
fuchsia.math/RectF?
|
WatchOrientation
Returns the orientation if it has changed from a previously returned value, or is called by a client for the first time. Frame callbacks received after receiving this callback reflect the new orientation.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
orientation |
Orientation
|
WatchResolution
Returns the resolution if it has changed from a previously returned value, or is called by a client for the first time. Frame callbacks received after receiving this callback reflect the new resolution.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
coded_size |
fuchsia.math/Size
|
STRUCTS
Configuration
Defined in fuchsia.camera3/device.fidl
Describes a distinct configuration for the camera.
| Field | Type | Description | Default |
|---|---|---|---|
streams |
vector<StreamProperties>:256
|
Descriptions of streams that are concurrently available in the configuration. |
No default |
FrameInfo resource
Defined in fuchsia.camera3/stream.fidl
Metadata concerning a given frame.
| Field | Type | Description | Default |
|---|---|---|---|
buffer_index |
uint32
|
Identifies the buffer used for this frame as an index into the most recently negotiated buffer collection. |
No default |
frame_counter |
uint64
|
A monotonically increasing counter indicating the number of frames written to this stream's most recently negotiated buffer collection. Clients can use this to detect dropped frames or generate nominal timestamps using the associated stream's framerate. |
No default |
timestamp |
zx/Time
|
The value of the system monotonic clock, measured at the time the hardware completed populating the buffer. |
No default |
release_fence |
handle<eventpair>
|
The client must close this when it has completed reading from the buffer. |
No default |
FrameRate
Defined in fuchsia.camera3/stream.fidl
The frequency at which a Stream produces frames. The value is numerator / denominator, with
units of frames-per-second (Hz). The representation is not necessarily an irreducible fraction.
| Field | Type | Description | Default |
|---|---|---|---|
numerator |
uint32
|
Fraction numerator. |
No default |
denominator |
uint32
|
Fraction denominator. This value will not be zero. |
No default |
StreamProperties
Defined in fuchsia.camera3/stream.fidl
Describes the properties of a given stream.
| Field | Type | Description | Default |
|---|---|---|---|
image_format |
fuchsia.sysmem/ImageFormat_2
|
Describes the native image format used by a stream. |
No default |
frame_rate |
FrameRate
|
Describes the framerate used by a stream. |
No default |
supports_crop_region |
bool
|
Indicates whether a stream supports the SetCropRegion method. |
No default |
ENUMS
Orientation strict
Type: uint32
Defined in fuchsia.camera3/stream.fidl
Describes the intended orientation of a given stream relative to its encoded data. For clarity, the documentation for each enum value is accompanied by an orientation of the chiral '⮬' symbol illustrating the orientation of the stream's encoded data.
| Name | Value | Description |
|---|---|---|
UP |
1 |
⮬: The content is already in the correct orientation. |
DOWN |
2 |
⮯: The content must be rotated 180 degrees to appear correct. |
LEFT |
3 |
⮫: The content must be rotated 90 degrees left (counter-clockwise) to appear correct. |
RIGHT |
4 |
⮨: The content must be rotated 90 degrees right (clockwise) to appear correct. |
UP_FLIPPED |
5 |
⮭: The content must be flipped horizontally to appear correct. |
DOWN_FLIPPED |
6 |
⮮: The content must be flipped horizontally then rotated 180 degrees to appear correct. |
LEFT_FLIPPED |
7 |
⮪: The content must be flipped horizontally then rotated 90 degrees left (counter-clockwise) to appear correct. |
RIGHT_FLIPPED |
8 |
⮩: The content must be flipped horizontally then rotated 90 degrees right (clockwise) to appear correct. |
TABLES
Configuration2
Defined in fuchsia.camera3/device.fidl
Describes a distinct configuration for the camera.
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
streams |
vector<StreamProperties2>:256
|
Descriptions of streams that are concurrently available in the configuration. |
FrameInfo2 resource
Defined in fuchsia.camera3/stream.fidl
Metadata concerning a given frame.
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
buffer_index |
uint32
|
Identifies the buffer used for this frame as an index into the most recently negotiated buffer collection. |
2 |
frame_counter |
uint64
|
A monotonically increasing counter indicating the number of frames written to this stream's most recently negotiated buffer collection. Clients can use this to detect dropped frames or generate nominal timestamps using the associated stream's framerate. |
3 |
timestamp |
zx/Time
|
The value of the system monotonic clock, measured at the time the hardware completed populating the buffer. |
4 |
capture_timestamp |
zx/Time
|
The value of the system monotonic clock, measured at the time the hardware completed populating the original buffer used to derive the contents of this buffer. |
5 |
release_fence |
handle<eventpair>
|
The client must close this when it has completed reading from the buffer. |
StreamProperties2
Defined in fuchsia.camera3/stream.fidl
Describes the properties of a given stream.
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
image_format |
fuchsia.sysmem/ImageFormat_2
|
Describes the native image format used by a stream. |
2 |
frame_rate |
FrameRate
|
Describes the framerate used by a stream. |
3 |
supports_crop_region |
bool
|
Indicates whether a stream supports the SetCropRegion method. |
4 |
supported_resolutions |
vector<fuchsia.math/Size>:256
|
Describes the precise resolutions supported by a stream, i.e. those for which SetResolution results in a WatchResolution callback of the same value. If empty, it indicates that the stream supports arbitrary resolutions. If non-empty, the list contains at least one element reflecting the native resolution specified by |image_format|. |
UNIONS
WatchDevicesEvent strict
Defined in fuchsia.camera3/device_watcher.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
existing |
DeviceId
|
Indicates an existing camera with the provided ID is still available. |
2 |
added |
DeviceId
|
Indicates a new camera with the provided ID is now available. |
3 |
removed |
DeviceId
|
Indicates an existing camera with the provided ID is no longer available. |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| 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 |
ALIASES
| Name | Value | Description |
|---|---|---|
| DeviceId |
uint64 |