| // Copyright 2020 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.camera3; |
| |
| using fuchsia.math; |
| using fuchsia.sysmem; |
| using zx; |
| |
| const MAX_RESOLUTIONS_PER_STREAM uint32 = 256; |
| |
| /// A Stream represents timing, sequencing, and other camera-specific properties applied to a buffer |
| /// collection. |
| protocol Stream { |
| /// Gets the properties associated with this stream. The value returned is identical to the one |
| /// corresponding to this stream as returned by |Device.GetConfigurations|. |
| @transitional |
| @deprecated("Use GetProperties2") |
| GetProperties() -> (struct { |
| properties StreamProperties; |
| }); |
| |
| /// Gets the properties associated with this stream. The value returned is identical to the one |
| /// corresponding to this stream as returned by |Device.GetConfigurations|. |
| @transitional |
| GetProperties2() -> (struct { |
| properties StreamProperties2; |
| }); |
| |
| /// 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. |
| SetCropRegion(struct { |
| region box<fuchsia.math.RectF>; |
| }); |
| |
| /// 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. |
| WatchCropRegion() -> (struct { |
| region box<fuchsia.math.RectF>; |
| }); |
| |
| /// 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. |
| SetResolution(struct { |
| coded_size fuchsia.math.Size; |
| }); |
| |
| /// 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. |
| WatchResolution() -> (struct { |
| coded_size fuchsia.math.Size; |
| }); |
| |
| /// 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. |
| SetBufferCollection(resource struct { |
| token client_end:<fuchsia.sysmem.BufferCollectionToken, optional>; |
| }); |
| |
| /// 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|. |
| WatchBufferCollection() -> (resource struct { |
| token client_end:fuchsia.sysmem.BufferCollectionToken; |
| }); |
| |
| /// 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. |
| WatchOrientation() -> (struct { |
| orientation Orientation; |
| }); |
| |
| /// See GetNextFrame2. |
| @transitional |
| @deprecated("Use GetNextFrame2") |
| GetNextFrame() -> (resource struct { |
| info FrameInfo; |
| }); |
| |
| /// 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. |
| @transitional |
| GetNextFrame2() -> (resource struct { |
| info FrameInfo2; |
| }); |
| |
| /// 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. |
| Rebind(resource struct { |
| request server_end:Stream; |
| }); |
| }; |
| |
| /// Metadata concerning a given frame. |
| type FrameInfo = resource struct { |
| /// Identifies the buffer used for this frame as an index into the most recently negotiated |
| /// buffer collection. |
| buffer_index uint32; |
| |
| /// 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. |
| frame_counter uint64; |
| |
| /// The value of the system monotonic clock, measured at the time the hardware completed |
| /// populating the buffer. |
| timestamp zx.time; |
| |
| /// The client must close this when it has completed reading from the buffer. |
| release_fence zx.handle:EVENTPAIR; |
| }; |
| |
| /// Metadata concerning a given frame. |
| type FrameInfo2 = resource table { |
| /// Identifies the buffer used for this frame as an index into the most recently negotiated |
| /// buffer collection. |
| 1: buffer_index uint32; |
| |
| /// 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. |
| 2: frame_counter uint64; |
| |
| /// The value of the system monotonic clock, measured at the time the hardware completed |
| /// populating the buffer. |
| 3: 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. |
| 4: capture_timestamp zx.time; |
| |
| /// The client must close this when it has completed reading from the buffer. |
| 5: release_fence zx.handle:EVENTPAIR; |
| }; |
| |
| /// 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. |
| type FrameRate = struct { |
| /// Fraction numerator. |
| numerator uint32; |
| |
| /// Fraction denominator. This value will not be zero. |
| denominator uint32; |
| }; |
| |
| /// Describes the properties of a given stream. |
| type StreamProperties = struct { |
| /// Describes the native image format used by a stream. |
| image_format fuchsia.sysmem.ImageFormat_2; |
| |
| /// Describes the framerate used by a stream. |
| frame_rate FrameRate; |
| |
| /// Indicates whether a stream supports the SetCropRegion method. |
| supports_crop_region bool; |
| }; |
| |
| /// Describes the properties of a given stream. |
| type StreamProperties2 = table { |
| /// Describes the native image format used by a stream. |
| 1: image_format fuchsia.sysmem.ImageFormat_2; |
| |
| /// Describes the framerate used by a stream. |
| 2: frame_rate FrameRate; |
| |
| /// Indicates whether a stream supports the SetCropRegion method. |
| 3: supports_crop_region bool; |
| |
| /// 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|. |
| 4: supported_resolutions vector<fuchsia.math.Size>:MAX_RESOLUTIONS_PER_STREAM; |
| }; |
| |
| /// 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. |
| type Orientation = strict enum { |
| /// ⮬: The content is already in the correct orientation. |
| UP = 1; |
| |
| /// ⮯: The content must be rotated 180 degrees to appear correct. |
| DOWN = 2; |
| |
| /// ⮫: The content must be rotated 90 degrees left (counter-clockwise) to appear correct. |
| LEFT = 3; |
| |
| /// ⮨: The content must be rotated 90 degrees right (clockwise) to appear correct. |
| RIGHT = 4; |
| |
| /// ⮭: The content must be flipped horizontally to appear correct. |
| UP_FLIPPED = 5; |
| |
| /// ⮮: The content must be flipped horizontally then rotated 180 degrees to appear correct. |
| DOWN_FLIPPED = 6; |
| |
| /// ⮪: The content must be flipped horizontally then rotated 90 degrees left (counter-clockwise) to appear correct. |
| LEFT_FLIPPED = 7; |
| |
| /// ⮩: The content must be flipped horizontally then rotated 90 degrees right (clockwise) to appear correct. |
| RIGHT_FLIPPED = 8; |
| }; |