// 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;

/// A Stream represents timing, sequencing, and other camera-specific properties applied to a buffer
/// collection.
protocol Stream {
    /// 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.
    WatchBufferCollection() -> (fuchsia.sysmem.BufferCollectionToken token);

    /// Request the next available frame for this stream. Returns when the stream has completed
    /// populating the buffer and may be read by the client, provided the number of unreleased
    /// buffers held by the client 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.
    GetNextFrame() -> (FrameInfo info);

    /// Request another connection to this Stream. This allows a client to delegate different
    /// operations to different coordinated clients.
    Rebind(request<Stream> request);
};

/// Metadata concerning a given frame.
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.
    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;
};