// 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 uint32 MAX_RESOLUTIONS_PER_STREAM = 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() -> (StreamProperties properties);

    /// 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() -> (StreamProperties2 properties);

    /// 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(fuchsia.math.RectF? region);

    /// 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() -> (fuchsia.math.RectF? region);

    /// 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(fuchsia.math.Size coded_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() -> (fuchsia.math.Size coded_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(fuchsia.sysmem.BufferCollectionToken? token);

    /// 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() -> (fuchsia.sysmem.BufferCollectionToken token);

    /// 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() -> (Orientation orientation);

    /// See GetNextFrame2.
    [Transitional, Deprecated = "Use GetNextFrame2"]
    GetNextFrame() -> (FrameInfo info);

    /// 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() -> (FrameInfo2 info);

    /// 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(request<Stream> request);
};

/// Metadata concerning a given frame.
resource struct FrameInfo {
    /// Identifies the buffer used for this frame as an index into the most recently negotiated
    /// buffer collection.
    uint32 buffer_index;

    /// 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.
    uint64 frame_counter;

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

    /// The client must close this when it has completed reading from the buffer.
    zx.handle:EVENTPAIR release_fence;
};

/// Metadata concerning a given frame.
resource table FrameInfo2 {
    /// Identifies the buffer used for this frame as an index into the most recently negotiated
    /// buffer collection.
    1: uint32 buffer_index;

    /// 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: uint64 frame_counter;

    /// The value of the system monotonic clock, measured at the time the hardware completed
    /// populating the buffer.
    3: zx.time timestamp;

    /// 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: zx.time capture_timestamp;

    /// The client must close this when it has completed reading from the buffer.
    5: zx.handle:EVENTPAIR release_fence;
};

/// 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.
struct FrameRate {
    /// Fraction numerator.
    uint32 numerator;

    /// Fraction denominator. This value will not be zero.
    uint32 denominator;
};

/// Describes the properties of a given stream.
struct StreamProperties {
    /// Describes the native image format used by a stream.
    fuchsia.sysmem.ImageFormat_2 image_format;

    /// Describes the framerate used by a stream.
    FrameRate frame_rate;

    /// Indicates whether a stream supports the SetCropRegion method.
    bool supports_crop_region;
};

/// Describes the properties of a given stream.
table StreamProperties2 {
    /// Describes the native image format used by a stream.
    1: fuchsia.sysmem.ImageFormat_2 image_format;

    /// Describes the framerate used by a stream.
    2: FrameRate frame_rate;

    /// Indicates whether a stream supports the SetCropRegion method.
    3: bool supports_crop_region;

    /// 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: vector<fuchsia.math.Size>:MAX_RESOLUTIONS_PER_STREAM supported_resolutions;
};

/// 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.
enum Orientation {
    /// ⮬: 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;
};