// Copyright 2019 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.camera2;

using fuchsia.sysmem;
using zx;

@discoverable
protocol Manager {
    /// Notifies the client when a camera becomes available.  A number of these events will
    /// be sent when a client first connects to this protocol.
    /// `device_id` is used to identify the camera.  The device_id should not change throughout
    /// the lifetime of the camera.
    /// `last_known_camera` is set to true when the Camera Manager has notified the client
    /// of all the devices it currently knows about.
    /// `description` describes the properties of the camera.
    -> OnDeviceAvailable(struct {
        device_id int32;
        description DeviceInfo;
        last_known_camera bool;
    });

    /// Notifies the client when a camera becomes unavailable.
    -> OnDeviceUnavailable(struct {
        device_id int32;
    });

    /// Notifies the client when a camera becomes muted or unmuted.
    /// `device_id` refers to the device_id from the description of a previous OnDeviceAvailable
    /// call.
    -> OnDeviceMuteChanged(struct {
        device_id int32;
        currently_muted bool;
    });

    /// AcknowledgeDeviceEvent must be called after any of the above events before more
    /// events will be sent.
    AcknowledgeDeviceEvent();

    /// Connect to a camera stream:
    /// `device_id` Refers to a specific device_id that has been advertised by OnDeviceAvailable.
    /// `constraints` contains a set of constraints on the requested stream.  The Camera
    /// Manager will attempt to find a stream that meets the constraints.  If multiple
    /// streams match, one of the matching streams will be connected.
    /// `token` refers to a Sysmem buffer allocation that will be used to pass images using
    /// the Stream protocol.  The Camera Manager will apply a BufferCollectionContraints
    /// related to the image format(s), so the client does not need to apply any
    /// ImageFormatConstraints.
    /// Sync is assumed to have been called on `token` before it is passed to
    /// ConnectToStream.
    /// Since `constraints` may not dictate a specific format, the initial format of images
    /// on the stream is indicated on the response.
    /// The connection is considered to be successful once a response has been given, unless
    /// `stream` is closed.
    ConnectToStream(resource struct {
        device_id int32;
        constraints StreamConstraints;
        token client_end:fuchsia.sysmem.BufferCollectionToken;
        stream server_end:Stream;
    }) -> (struct {
        format fuchsia.sysmem.ImageFormat_2;
    });
};

@discoverable
protocol MuteControl {
    /// Mutes a camera.  This is independent from stopping or closing a stream.  A muted
    /// camera will not produce any more images until
    /// unmute is called.  You can still connect to streams from a muted camera, but they
    /// will not produce frames until the camera is unmuted.
    /// `device_id` refers to the device_id from a previous OnDeviceAvailable call.
    Mute(struct {
        device_id int32;
    }) -> (struct {
        status zx.status;
    });
    Unmute(struct {
        device_id int32;
    }) -> (struct {
        status zx.status;
    });
};

/// These constraints are given to the Camera Manager when requesting a stream.  The
/// Camera Manager will use these constraints to match an appropriate stream.
type StreamConstraints = table {
    /// A table that describes the properties of the stream. Any properties specified will
    /// be considered requirements for matching streams.
    1: properties StreamProperties;

    /// If specified, the stream will be created using this index for the initial format index.
    /// If unspecified, the first stream format will be used.
    2: format_index uint32;
};

type DeviceType = strict enum {
    BUILTIN = 1;
    VIRTUAL = 2;
};

/// Identifying information about the device.
type DeviceInfo = table {
    /// Information from physical device enumeration:
    1: vendor_id uint16;
    2: vendor_name string:255;
    3: product_id uint16;
    4: product_name string:255;

    /// Information about the type of device:
    5: type DeviceType;
};