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