zircon/system/fidl/fuchsia-camera-common/common.fidl

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

// This FIDL file provides the common types and protocols shared between
// fuchsia.hardware.camera from Zircon and fuchsia.camera from the SDK.
// TODO(eweeks): Rename this library to fuchsia.camera

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

// TODO(braval): This set of declarations would be the bitfield: CameraOutputCapabilities.
const uint32 CAMERA_OUTPUT_UNKNOWN = 0;
const uint32 CAMERA_OUTPUT_STILL_IMAGE = 0x01;
const uint32 CAMERA_OUTPUT_BURST = 0x02;
const uint32 CAMERA_OUTPUT_STREAM = 0x04;
const uint32 CAMERA_OUTPUT_HDR = 0x08;
const uint32 CAMERA_OUTPUT_DEPTH = 0x10;
const uint32 CAMERA_OUTPUT_STEREO = 0x20;

/// Identifying information about the device.
// TODO(braval): Uncomment the strings when zircon supports llcpp bindings
// TODO(CAM-12): Add CameraPose, when we can actually use it.
struct DeviceInfo {
    /// Currently populated by the camera manager
    uint64 camera_id;
    uint16 vendor_id;
    /// string vendor_name;
    uint16 product_id;
    /// string product_name;
    /// string serial_number;
    /// The maximum number of stream interfaces that the device can support
    /// simultaneously.
    uint16 max_stream_count;
    uint32 output_capabilities;
};

/// Status to be set when a frame is signaled available.
enum FrameStatus {
    OK = 1;
    /// An error occurred during the production of a frame.
    /// No data will be available in the data buffer corresponding to this
    /// notification.
    ERROR_FRAME = 2;

    /// No space was available in the data buffer, resulting in a dropped frame.
    ERROR_BUFFER_FULL = 3;
};

/// Extra information associated with the frame.
struct Metadata {
    int64 timestamp;
};

/// Sent by the driver to the client when a frame is available for processing,
/// or an error occurred.
// TODO(eweeks): Replace struct with three parameter event.
struct FrameAvailableEvent {
    /// Non zero if an error occurred.
    FrameStatus frame_status;

    /// The index of the buffer in the buffer collection.
    uint32 buffer_id;

    /// Any associated metadata such as timestamp.
    Metadata metadata;
};

/// The number of frames being produced every second.
struct FrameRate {
    /// The frame rate is frames_per_sec_numerator / frames_per_sec_denominator.
    uint32 frames_per_sec_numerator;
    uint32 frames_per_sec_denominator;
};

/// Video format includes the image format and frame rate of frames being produced.
struct VideoFormat {
    fuchsia.sysmem.ImageFormat format;
    FrameRate rate;
};

/// Protocol shared between the driver and the consumer.
[Layout = "Simple"]
protocol Stream {
    /// Starts the streaming of frames.
    Start();

    /// Stops the streaming of frames.
    Stop();

    /// Unlocks the specified frame, allowing the driver to reuse the memory.
    ReleaseFrame(uint32 buffer_id);

    /// Sent by the driver to the client when a frame is available for processing,
    /// or an error occurred.
    -> OnFrameAvailable(FrameAvailableEvent frame);
};