// 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.hardware.camera.sensor;

using fuchsia.hardware.camera;
using zx;

const EXTENSION_VALUE_ARRAY_LEN uint32 = 32;

/// A type used to distinguish extension parameters.
type ExtensionValueDataType = strict union {
    1: int_value int32;
    2: uint_value uint32;
    3: byte_array_value array<uint8, EXTENSION_VALUE_ARRAY_LEN>;
    4: dimension_value fuchsia.hardware.camera.Dimensions;
    5: constraints_value fuchsia.hardware.camera.MinMaxConstraints;
    6: frame_rate_info_value array<FrameRateInfo, EXTENSION_VALUE_ARRAY_LEN>;
};

type PixelType = strict enum : uint8 {
    RAW8 = 1;
    RAW10 = 2;
    RAW12 = 3;
};

type DynamicRangeMode = strict enum : uint8 {
    LINEAR = 1;
    WIDE = 2;
};

type BinningMode = strict enum : uint8 {
    NONE = 1;
    ADDITIVE = 2;
    AVERAGE = 3;
};

type SamplingParams = struct {
    mode BinningMode;
    bin_amount uint32;
    skip_amount uint32;
};

type ReadoutConfig = struct {
    /// Describes sampling parameters for the x plane.
    sampling_x SamplingParams;
    /// Describes sampling parameters for the y plane.
    sampling_y SamplingParams;
    /// The x and y offset as well as the width and height for cropping.
    scaler_crop fuchsia.hardware.camera.Rect;
};

/// A sensor can support several different predefined modes.
/// This structure keeps all necessary information about a mode.
// TODO(https://fxbug.dev/42133055): Move non-sensor-specific params out of this struct.
type OperatingMode = struct {
    /// This mode's index.
    idx uint8;
    /// This mode's identifying string.
    identifier string:MAX;
    /// Maximum frames per second.
    fps uint32;
    /// Input resolution, where |x| is pixel width and |y| is pixel height.
    resolution_in fuchsia.hardware.camera.Dimensions;
    /// Output resolution, where |x| is pixel width and |y| is pixel height.
    resolution_out fuchsia.hardware.camera.Dimensions;
    /// How many exposures this mode supports.
    exposures uint8;
    /// A mode that reflects what dynamic range technique is being used.
    dr_mode DynamicRangeMode;
    /// The pixel type (e.g. whether the output is in RAW8, RAW10, etc. format).
    pixel_type PixelType;
    /// Lane count.
    lanes uint8;
    /// MBps per lane.
    mbps uint32;
    /// Line time.
    line_time float32;
    /// Frame time.
    frame_time float32;
    /// A structure containing information on binning, skipping, and scaling
    /// operations carried out on frame data.
    readout ReadoutConfig;
};

/// This structure maps the sensor's frame rates to coarse max integration time.
type FrameRateInfo = struct {
    frame_rate fuchsia.hardware.camera.FrameRate;
    max_coarse_integration_time uint32;
};

// TODO(https://fxbug.dev/42133056): Incorporate muting behavior into documentation. Add arg/return value info.
// TODO(https://fxbug.dev/42134307): Add a versioning mechanism.
// TODO(https://fxbug.dev/42133059): Transition methods to use [Async].
/// Exposes a product-agnostic interface to the camera's sensor.
/// Allows clients to get and set sensor constraints, sensor mode,
/// and its dynamic operating state.
///
/// Most methods provide a `zx.Status` return value. This can be:
///    ZX_OK                      - The operation was successful.
///    ZX_ERR_INTERNAL            - The sensor has not been initialized or has encountered an
///                                 otherwise unspecified error.
///    ZX_ERR_NOT_SUPPORTED       - The operation is not supported on the current device.
///    ZX_ERR_INVALID_ARGS        - Invalid args for this operation.
///    ZX_ERR_OUT_OF_RANGE        - Args fall outside of min/max constraints.
///    ZX_ERR_BUFFER_TOO_SMALL    - Buffer provided cannot hold all required data.
///    ZX_ERR_IO_NOT_PRESENT      - There is no sensor device present or bound.
@transport("Banjo")
@banjo_layout("ddk-protocol")
closed protocol CameraSensor2 {
    /// Initializes the sensor.
    strict Init() -> (struct {
        s zx.Status;
    });
    /// De-Initializes the sensor.
    strict DeInit() -> (struct {
        s zx.Status;
    });

    /// Retrieves the sensor's ID.
    strict GetSensorId() -> (struct {
        s zx.Status;
        id uint32;
    });

    /// Retrieve a vector of available modes.
    strict GetAvailableModes() -> (struct {
        s zx.Status;
        modes vector<OperatingMode>:MAX;
    });
    /// Use a specific mode for the initialization sequence.
    strict SetMode(struct {
        mode uint32;
    }) -> (struct {
        s zx.Status;
    });

    /// Start streaming.
    /// Is safe to call this if streaming is already started.
    strict StartStreaming() -> (struct {
        s zx.Status;
    });
    /// Stop streaming.
    /// It is safe to call this if streaming is already stopped.
    strict StopStreaming() -> ();

    // Exposure Settings

    /// Retrieve analog gain value.
    strict GetAnalogGain() -> (struct {
        s zx.Status;
        gain float32;
    });
    /// Changes analog gain value.
    strict SetAnalogGain(struct {
        gain float32;
    }) -> (struct {
        s zx.Status;
        gain float32;
    });
    /// Retrieve digital gain value.
    strict GetDigitalGain() -> (struct {
        s zx.Status;
        gain float32;
    });
    /// Changes digital gain value.
    strict SetDigitalGain(struct {
        gain float32;
    }) -> (struct {
        s zx.Status;
        gain float32;
    });
    /// Retrieve integration time value.
    strict GetIntegrationTime() -> (struct {
        s zx.Status;
        int_time float32;
    });
    /// Changes Integration Time.
    strict SetIntegrationTime(struct {
        int_time float32;
    }) -> (struct {
        s zx.Status;
        int_time float32;
    });

    /// Update the sensor with new parameters.
    strict Update() -> (struct {
        s zx.Status;
    });

    // OTP

    /// Retrieve the total size of the data stored in the OTP module.
    strict GetOtpSize() -> (struct {
        s zx.Status;
        size uint32;
    });
    /// Retrieve the specified amount of OTP data at the offset and write them to
    /// the provided vmo.
    strict GetOtpData(struct {
        byte_count uint32;
        offset uint32;
    }) -> (resource struct {
        s zx.Status;
        otp_data zx.Handle:VMO;
    });

    // Test Controls

    /// Retrieves the test pattern mode the sensor is set to.
    ///    0            – No pattern (default)
    ///    1            – Solid colour
    ///    2            – 100% colour bars
    ///    3            – Fade to grey’ colour bars
    ///    4            - PN9
    ///    5-255        - Reserved
    ///    256-65535    – Manufacturer specific
    strict GetTestPatternMode() -> (struct {
        s zx.Status;
        value uint16;
    });
    /// Changes the sensor's test pattern mode.
    strict SetTestPatternMode(struct {
        mode uint16;
    }) -> (struct {
        s zx.Status;
    });
    /// Retrieves the test pattern data being used.
    strict GetTestPatternData() -> (struct {
        s zx.Status;
        data fuchsia.hardware.camera.ColorVal;
    });
    /// Changes data used by the test pattern. Only used by certain modes.
    strict SetTestPatternData(struct {
        data fuchsia.hardware.camera.ColorVal;
    }) -> (struct {
        s zx.Status;
    });

    /// Retrieves the test cursor data being used.
    strict GetTestCursorData() -> (struct {
        s zx.Status;
        data fuchsia.hardware.camera.Rect;
    });
    /// Changes the sensor's cursor-related parameters.
    strict SetTestCursorData(struct {
        data fuchsia.hardware.camera.Rect;
    }) -> (struct {
        s zx.Status;
    });

    // Other Capabilities

    /// This subset of the API provides implementers with the flexibility to provide custom
    /// endpoints for elements not otherwise included.
    /// Retrieves the specified element. The caller must reference the implementer's ID list.
    strict GetExtensionValue(struct {
        id uint64;
    }) -> (struct {
        s zx.Status;
        value ExtensionValueDataType;
    });
    /// This subset of the API provides implementers with the flexibility to provide custom
    /// endpoints for elements not otherwise included.
    /// Changes the specified element. The caller must reference the implementer's ID list.
    strict SetExtensionValue(struct {
        id uint64;
        value ExtensionValueDataType;
    }) -> (struct {
        s zx.Status;
        value ExtensionValueDataType;
    });
};