fuchsia.camera3

Added: 7

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

NameType
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

NameType
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

NameType
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

NameType
identifier string[256]?

Rebind

Request another connection to this Device. This allows a client to delegate different operations to different coordinated clients.

Request

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
request server_end<Stream>

SetBufferCollection

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

NameType
token fuchsia.sysmem/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

NameType
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

NameType
coded_size fuchsia.math/Size

WatchBufferCollection

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

NameType
token fuchsia.sysmem/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

NameType
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

NameType
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

NameType
coded_size fuchsia.math/Size

STRUCTS

Configuration

Defined in fuchsia.camera3/device.fidl

Describes a distinct configuration for the camera.

FieldTypeDescriptionDefault
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.

FieldTypeDescriptionDefault
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.

FieldTypeDescriptionDefault
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.

FieldTypeDescriptionDefault
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.

NameValueDescription
1

⮬: The content is already in the correct orientation.

2

⮯: The content must be rotated 180 degrees to appear correct.

3

⮫: The content must be rotated 90 degrees left (counter-clockwise) to appear correct.

4

⮨: The content must be rotated 90 degrees right (clockwise) to appear correct.

5

⮭: The content must be flipped horizontally to appear correct.

6

⮮: The content must be flipped horizontally then rotated 180 degrees to appear correct.

7

⮪: The content must be flipped horizontally then rotated 90 degrees left (counter-clockwise) to appear correct.

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.

OrdinalFieldTypeDescription
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.

OrdinalFieldTypeDescription
buffer_index uint32

Identifies the buffer used for this frame as an index into the most recently negotiated buffer collection.

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.

timestamp zx/Time

The value of the system monotonic clock, measured at the time the hardware completed populating the buffer.

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.

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.

OrdinalFieldTypeDescription
image_format fuchsia.sysmem/ImageFormat_2

Describes the native image format used by a stream.

frame_rate FrameRate

Describes the framerate used by a stream.

supports_crop_region bool

Indicates whether a stream supports the SetCropRegion method.

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

OrdinalVariantTypeDescription
existing DeviceId

Indicates an existing camera with the provided ID is still available.

added DeviceId

Indicates a new camera with the provided ID is now available.

removed DeviceId

Indicates an existing camera with the provided ID is no longer available.

CONSTANTS

NameValueTypeDescription
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

NameValueDescription
DeviceId uint64