// Copyright 2018 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.camera;

using fuchsia.camera.common;
using fuchsia.sysmem;

// A stream that the camera manager can provide.  Video streams reference a
// a camera, but may have additional hardware and bandwidth restrictions
// from and ISP or other processing units.
// This is being deprecated - please use VideoStreamV2 (below).
struct VideoStream {
    // The camera_id corresponds to the camera_id that is given in the DeviceInfo
    // received from GetDevices.
    uint64 camera_id;
    // The requested video format.  Note that this is field is necessary to
    // set The frame rate, even when calling CreateStream.
    // When calling CreateStream, format.format should match buffer_info.format.
    VideoFormat format;
};

// Preferred version of stream.
// A version of stream that relies on definition of VideoFormat coming out of
// fuchsia.hardware.camera. Streams reference a camera, but may have additional
// hardware and bandwidth restrictions from an ISP or other processing units.
// New code should depend on this as the other version will be deprecated when
// dependencies are removed.
struct VideoStreamV2 {
    // The camera_id corresponds to the camera_id that is given in DeviceInfo
    // received from GetDevices.
    uint64 camera_id;
    // The requested video format. Note that this field is necessary to set the
    // frame rate, even when calling CreateStream. When calling CreateStream
    // format.format should match buffer_info.format.
    fuchsia.camera.common.VideoFormat format;
};

// The Camera Manager grants access to individual or sets of cameras
// 1) You request the list of cameras, which gives you camera descriptions
// 2) You request the list of formats available for the camera to which you
//    wish to connect.
// 3) You request a Stream interface using CreateStream.
[Discoverable]
protocol Manager {
    // Returns a list of all the video devices that are currently plugged in
    // and enumerated.  The camera_id field of the DeviceInfo is used to specify
    // a device in GetFormats, GetStream and GetStreamAndBufferCollection.
    GetDevices() -> (vector<DeviceInfo> descriptions);

    // Get all the available formats for a camera.
    // |camera_id| is obtained from a DeviceInfo returned by GetDevices.
    GetFormats(uint64 camera_id, uint32 index)
        -> (vector<VideoFormat> formats, uint32 total_format_count);

    // Create a Stream with the specified access rights.  This may not succeed.
    // If it does succeed, the Stream will have the rights indicated.
    // |buffer_info| contains a set of buffers to be used with the Stream.
    // This is being deprecated - please use CreateStreamV2.
    CreateStream(VideoStream request,
                 fuchsia.sysmem.BufferCollectionInfo buffer_info,
                 request<Stream> stream, handle<eventpair> client_token);

    // Create a Stream with the specified access rights.  This may not succeed.
    // If it does succeed, the Stream will have the rights indicated.
    // |buffer_info| contains a set of buffers to be used with the Stream.
    [Transitional="This is meant to replace CreateStream"]
    CreateStreamV2(VideoStreamV2 request,
                   fuchsia.sysmem.BufferCollectionInfo buffer_info,
                   request<fuchsia.camera.common.Stream> stream,
                   handle<eventpair> client_token);

};