/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.camera.device@3.4;

import @3.2::RequestTemplate;
import @3.2::StreamConfigurationMode;
import @3.2::Stream;
import @3.3::HalStream;
import @3.2::CameraMetadata;
import @3.2::CaptureRequest;
import @3.2::CaptureResult;

/**
 * Stream:
 *
 * A descriptor for a single camera input or output stream. A stream is defined
 * by the framework by its buffer resolution and format, and additionally by the
 * HAL with the gralloc usage flags and the maximum in-flight buffer count.
 *
 * This version extends the @3.2 Stream with the physicalCameraId and bufferSize field.
 */
struct Stream {
    /**
     * The definition of Stream from the prior version
     */
    @3.2::Stream v3_2;

    /**
     * The physical camera id this stream belongs to.
     *
     * If the camera device is not a logical multi camera, or if the camera is a logical
     * multi camera but the stream is not a physical output stream, this field will point to a
     * 0-length string.
     *
     * A logical multi camera is a camera device backed by multiple physical cameras that
     * are also exposed to the application. And for a logical multi camera, a physical output
     * stream is an output stream specifically requested on an underlying physical camera.
     *
     * A logical camera is a camera device backed by multiple physical camera
     * devices. And a physical stream is a stream specifically requested on a
     * underlying physical camera device.
     *
     * For an input stream, this field is guaranteed to be a 0-length string.
     *
     * When not empty, this field is the <id> field of one of the full-qualified device
     * instance names returned by getCameraIdList().
     */
    string physicalCameraId;

    /**
     * The size of a buffer from this Stream, in bytes.
     *
     * For non PixelFormat::BLOB formats, this entry must be 0 and HAL should use
     * android.hardware.graphics.mapper lockYCbCr API to get buffer layout.
     *
     * For BLOB format with dataSpace Dataspace::DEPTH, this must be zero and and HAL must
     * determine the buffer size based on ANDROID_DEPTH_MAX_DEPTH_SAMPLES.
     *
     * For BLOB format with dataSpace Dataspace::JFIF, this must be non-zero and represent the
     * maximal size HAL can lock using android.hardware.graphics.mapper lock API.
     *
     */
    uint32_t bufferSize;
};

/**
 * StreamConfiguration:
 *
 * Identical to @3.2::StreamConfiguration, except that it contains session
 * parameters, and the streams vector contains @3.4::Stream.
 */
struct StreamConfiguration {
    /**
     * An array of camera stream pointers, defining the input/output
     * configuration for the camera HAL device.
     */
    vec<Stream> streams;

    /**
     * The definition of operation mode from prior version.
     *
     */
    StreamConfigurationMode operationMode;

    /**
     * Session wide camera parameters.
     *
     * The session parameters contain the initial values of any request keys that were
     * made available via ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. The Hal implementation
     * can advertise any settings that can potentially introduce unexpected delays when
     * their value changes during active process requests. Typical examples are
     * parameters that trigger time-consuming HW re-configurations or internal camera
     * pipeline updates. The field is optional, clients can choose to ignore it and avoid
     * including any initial settings. If parameters are present, then hal must examine
     * their values and configure the internal camera pipeline accordingly.
     */
    CameraMetadata sessionParams;
};

/**
 * HalStream:
 *
 * The camera HAL's response to each requested stream configuration.
 *
 * This version extends the @3.3 HalStream with the physicalCameraId
 * field
 */
struct HalStream {
    /**
     * The definition of HalStream from the prior version.
     */
    @3.3::HalStream v3_3;

    /**
     * The physical camera id the current Hal stream belongs to.
     *
     * If current camera device isn't a logical camera, or the Hal stream isn't
     * from a physical camera of the logical camera, this must be an empty
     * string.
     *
     * A logical camera is a camera device backed by multiple physical camera
     * devices.
     *
     * When not empty, this field is the <id> field of one of the full-qualified device
     * instance names returned by getCameraIdList().
     */
    string physicalCameraId;
};

/**
 * HalStreamConfiguration:
 *
 * Identical to @3.3::HalStreamConfiguration, except that it contains @3.4::HalStream entries.
 *
 */
struct HalStreamConfiguration {
    vec<HalStream> streams;
};

/**
 * PhysicalCameraSetting:
 *
 * Individual camera settings for logical camera backed by multiple physical devices.
 * Clients are allowed to pass separate settings for each physical device that has
 * corresponding configured HalStream and the respective stream id is present in the
 * output buffers of the capture request.
 */
struct PhysicalCameraSetting {
    /**
     * If non-zero, read settings from request queue instead
     * (see ICameraDeviceSession.getCaptureRequestMetadataQueue).
     * If zero, read settings from .settings field.
     *
     * The v3_2 settings metadata is read first from the FMQ, followed by
     * the physical cameras' settings metadata starting from index 0.
     */
    uint64_t fmqSettingsSize;

    /**
     * Contains the physical device camera id. Any settings passed by client here
     * should be applied for this physical device. In case the physical id is invalid or
     * it is not present among the last configured streams, Hal should fail the process
     * request and return Status::ILLEGAL_ARGUMENT.
     */
    string physicalCameraId;

    /**
     * If fmqSettingsSize is zero, the settings buffer contains the capture and
     * processing parameters for the physical device with id 'physicalCameraId'.
     * As a special case, an empty settings buffer indicates that the
     * settings are identical to the most-recently submitted capture request.
     * An empty buffer cannot be used as the first submitted request after
     * a configureStreams() call.
     *
     * This field must be used if fmqSettingsSize is zero. It must not be used
     * if fmqSettingsSize is non-zero.
     */
    CameraMetadata settings;
};

/**
 * CaptureRequest:
 *
 * A single request for image capture/buffer reprocessing, sent to the Camera
 * HAL device by the framework in processCaptureRequest().
 *
 * The request contains the settings to be used for this capture, and the set of
 * output buffers to write the resulting image data in. It may optionally
 * contain an input buffer, in which case the request is for reprocessing that
 * input buffer instead of capturing a new image with the camera sensor. The
 * capture is identified by the frameNumber.
 *
 * In response, the camera HAL device must send a CaptureResult
 * structure asynchronously to the framework, using the processCaptureResult()
 * callback.
 *
 * Identical to @3.2::CaptureRequest, except that it contains
 * @3.4::physCamSettings vector.
 *
 * With 3.4 CaptureRequest, there can be multiple sources of metadata settings.
 * The @3.2::CaptureRequest v3_2 and each of the PhysicalCameraSetting in
 * physicalCameraSettings can contain settings, and each buffer may have
 * metadata settings from a different source.
 *
 * For both @3.2::CaptureRequest and PhysicalCameraSetting, the settings can be
 * passed from framework to HAL using either hwbinder or FMQ; both of the
 * structs have the fields fmqSettingsSize and settings to pass the metadata.
 * When metadata settings are passed using hwbinder, fmqSettingsSize == 0 and
 * settings field contains the metadata for the HAL to read. When metadata
 * settings comes from FMQ, fmqSettingsSize > 0 and HAL reads metadata from FMQ.
 * For the purposes of selecting which settings to use, it does not matter
 * whether it comes from hwbinder or FMQ. When the below specifications say that
 * v3_2 has settings or a PhysicalCameraSetting has settings, it could refer to
 * either hwbinder or FMQ, whichever is specified in the struct.
 *
 * Below is the logic that the HAL must follow for applying the metadata
 * settings when it receives a CaptureRequest request in
 * processCaptureRequest_3_4. Note that HAL must be capable of storing both the
 * request.v3_2 settings and the PhysicalCameraSetting settings for each
 * physical device.
 * - Case 1 - request.v3_2 has settings, request.physicalCameraSettings vector
 *   is empty:
 *   - Store the request.v3_2 settings, overwriting the previously stored
 *     request.v3_2 settings and clearing all previously stored physical device
 *     settings.
 *   - Apply the settings from the request.v3_2 to all buffers.
 * - Case 2 - request.v3_2 has settings, request.physicalCameraSettings vector
 *   is not empty:
 *   - Store the request.v3_2 settings, overwriting the previously stored
 *     request.v3_2 settings.
 *   - Each PhysicalCameraSetting in request.physicalCameraSettings must have
 *     settings; if not, return error.
 *   - For each PhysicalCameraSetting in request.physicalCameraSettings, store
 *     the settings, overwriting the previously stored settings for this
 *     physical camera; apply these settings to the buffers belonging to the
 *     stream for this device.
 *   - If there are any stored physical camera settings which do not correspond
 *     to one of the PhysicalCameraSetting in this request, clear them.
 *   - Apply the request.v3_2 settings to all buffers belonging to streams not
 *     covered by one of the PhysicalCameraSetting in this request.
 * - Case 3 - request.v3_2 does not have settings,
 *   request.physicalCameraSettings vector is empty:
 *   - Clear all previously stored physical device settings.
 *   - Apply the stored request.v3_2 settings to all buffers. If there is no
 *     stored request.v3_2 settings, return error.
 * - Case 4 - request.v3_2 does not have settings,
 *   request.physicalCameraSettings vector is not empty:
 *   - If request.physicalCameraSettings does not have the same set of physical
 *     cameras as the stored physical camera settings, return error.
 *   - Each PhysicalCameraSetting in request.physicalCameraSettings must not
 *     have settings; if any do have settings, return error.
 *   - For each PhysicalCameraSetting in request.physicalCameraSettings, apply
 *     the previously stored settings for this physical camera to the buffers
 *     belonging to the stream for this device.
 *   - Apply the stored request.v3_2 settings to all buffers belonging to
 *     streams not covered by one of the PhysicalCameraSetting in this request.
 *     If there is no stored request.v3_2 settings, return error.
 *
 * For the first request received by the HAL, only Case 1 and Case 2 are
 * allowed.
 */
struct CaptureRequest {
    /**
     * The definition of CaptureRequest from prior version.
     */
    @3.2::CaptureRequest v3_2;

    /**
     * A vector containing individual camera settings for logical camera backed by multiple physical
     * devices. In case the vector is empty, Hal should use the settings field in 'v3_2'. The
     * individual settings should only be honored for physical devices that have respective Hal
     * stream. Physical devices that have a corresponding Hal stream but don't have attached
     * settings here should use the settings field in 'v3_2'.
     * If any of the physical settings in the array are applied on one or more devices, then the
     * visual effect on any Hal streams attached to the logical camera is undefined.
     */
    vec<PhysicalCameraSetting> physicalCameraSettings;
};

/**
 * PhysicalCameraMetadata:
 *
 * Individual camera metadata for a physical camera as part of a logical
 * multi-camera. Camera HAL should return one such metadata for each physical
 * camera being requested on.
 */
struct PhysicalCameraMetadata {
    /**
     * If non-zero, read metadata from result metadata queue instead
     * (see ICameraDeviceSession.getCaptureResultMetadataQueue).
     * If zero, read metadata from .metadata field.
     *
     * The v3_2 CaptureResult metadata is read first from the FMQ, followed by
     * the physical cameras' metadata starting from index 0.
     */
    uint64_t fmqMetadataSize;

    /**
     * Contains the physical device camera id. As long as the corresponding
     * processCaptureRequest requests on a particular physical camera stream,
     * the metadata for that physical camera should be generated for the capture
     * result. */
    string physicalCameraId;

    /**
     * If fmqMetadataSize is zero, the metadata buffer contains the metadata
     * for the physical device with physicalCameraId.
     */
    CameraMetadata metadata;
};

/**
 * CaptureResult:
 *
 * Identical to @3.2::CaptureResult, except that it contains a list of
 * physical camera metadata.
 *
 * Physical camera metadata needs to be generated if and only if a
 * request is pending on a stream from that physical camera. For example,
 * if the processCaptureRequest call doesn't request on physical camera
 * streams, the physicalCameraMetadata field of the CaptureResult being returned
 * should be an 0-size vector. If the processCaptureRequest call requests on
 * streams from one of the physical camera, the physicalCameraMetadata field
 * should contain one metadata describing the capture from that physical camera.
 *
 * For a CaptureResult that contains physical camera metadata, its
 * partialResult field must be android.request.partialResultCount. In other
 * words, the physicalCameraMetadata must only be contained in a final capture
 * result.
 */
struct CaptureResult {
    /**
     * The definition of CaptureResult from the prior version.
     */
    @3.2::CaptureResult v3_2;

    /**
     * The physical metadata for logical multi-camera.
     */
    vec<PhysicalCameraMetadata> physicalCameraMetadata;
};