/* SPDX-License-Identifier: Apache-2.0 */
/*
 * Copyright (C) 2013-2018 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.
 */

#ifndef ANDROID_INCLUDE_CAMERA3_H
#define ANDROID_INCLUDE_CAMERA3_H

#include <system/camera_metadata.h>
#include "camera_common.h"

/**
 * Camera device HAL 3.5[ CAMERA_DEVICE_API_VERSION_3_5 ]
 *
 * This is the current recommended version of the camera device HAL.
 *
 * Supports the android.hardware.Camera API, and as of v3.2, the
 * android.hardware.camera2 API as LIMITED or above hardware level.
 *
 * Camera devices that support this version of the HAL must return
 * CAMERA_DEVICE_API_VERSION_3_5 in camera_device_t.common.version and in
 * camera_info_t.device_version (from camera_module_t.get_camera_info).
 *
 * CAMERA_DEVICE_API_VERSION_3_3 and above:
 *    Camera modules that may contain version 3.3 or above devices must
 *    implement at least version 2.2 of the camera module interface (as defined
 *    by camera_module_t.common.module_api_version).
 *
 * CAMERA_DEVICE_API_VERSION_3_2:
 *    Camera modules that may contain version 3.2 devices must implement at
 *    least version 2.2 of the camera module interface (as defined by
 *    camera_module_t.common.module_api_version).
 *
 * <= CAMERA_DEVICE_API_VERSION_3_1:
 *    Camera modules that may contain version 3.1 (or 3.0) devices must
 *    implement at least version 2.0 of the camera module interface
 *    (as defined by camera_module_t.common.module_api_version).
 *
 * See camera_common.h for more versioning details.
 *
 * Documentation index:
 *   S1. Version history
 *   S2. Startup and operation sequencing
 *   S3. Operational modes
 *   S4. 3A modes and state machines
 *   S5. Cropping
 *   S6. Error management
 *   S7. Key Performance Indicator (KPI) glossary
 *   S8. Sample Use Cases
 *   S9. Notes on Controls and Metadata
 *   S10. Reprocessing flow and controls
 */

/**
 * S1. Version history:
 *
 * 1.0: Initial Android camera HAL (Android 4.0) [camera.h]:
 *
 *   - Converted from C++ CameraHardwareInterface abstraction layer.
 *
 *   - Supports android.hardware.Camera API.
 *
 * 2.0: Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
 *
 *   - Sufficient for implementing existing android.hardware.Camera API.
 *
 *   - Allows for ZSL queue in camera service layer
 *
 *   - Not tested for any new features such manual capture control, Bayer RAW
 *     capture, reprocessing of RAW data.
 *
 * 3.0: First revision of expanded-capability HAL:
 *
 *   - Major version change since the ABI is completely different. No change to
 *     the required hardware capabilities or operational model from 2.0.
 *
 *   - Reworked input request and stream queue interfaces: Framework calls into
 *     HAL with next request and stream buffers already dequeued. Sync framework
 *     support is included, necessary for efficient implementations.
 *
 *   - Moved triggers into requests, most notifications into results.
 *
 *   - Consolidated all callbacks into framework into one structure, and all
 *     setup methods into a single initialize() call.
 *
 *   - Made stream configuration into a single call to simplify stream
 *     management. Bidirectional streams replace STREAM_FROM_STREAM construct.
 *
 *   - Limited mode semantics for older/limited hardware devices.
 *
 * 3.1: Minor revision of expanded-capability HAL:
 *
 *   - configure_streams passes consumer usage flags to the HAL.
 *
 *   - flush call to drop all in-flight requests/buffers as fast as possible.
 *
 * 3.2: Minor revision of expanded-capability HAL:
 *
 *   - Deprecates get_metadata_vendor_tag_ops.  Please use get_vendor_tag_ops
 *     in camera_common.h instead.
 *
 *   - register_stream_buffers deprecated. All gralloc buffers provided
 *     by framework to HAL in process_capture_request may be new at any time.
 *
 *   - add partial result support. process_capture_result may be called
 *     multiple times with a subset of the available result before the full
 *     result is available.
 *
 *   - add manual template to camera3_request_template. The applications may
 *     use this template to control the capture settings directly.
 *
 *   - Rework the bidirectional and input stream specifications.
 *
 *   - change the input buffer return path. The buffer is returned in
 *     process_capture_result instead of process_capture_request.
 *
 * 3.3: Minor revision of expanded-capability HAL:
 *
 *   - OPAQUE and YUV reprocessing API updates.
 *
 *   - Basic support for depth output buffers.
 *
 *   - Addition of data_space field to camera3_stream_t.
 *
 *   - Addition of rotation field to camera3_stream_t.
 *
 *   - Addition of camera3 stream configuration operation mode to camera3_stream_configuration_t
 *
 * 3.4: Minor additions to supported metadata and changes to data_space support
 *
 *   - Add ANDROID_SENSOR_OPAQUE_RAW_SIZE static metadata as mandatory if
 *     RAW_OPAQUE format is supported.
 *
 *   - Add ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE static metadata as
 *     mandatory if any RAW format is supported
 *
 *   - Switch camera3_stream_t data_space field to a more flexible definition,
 *     using the version 0 definition of dataspace encoding.
 *
 *   - General metadata additions which are available to use for HALv3.2 or
 *     newer:
 *     - ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
 *     - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
 *     - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
 *     - ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
 *     - ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
 *     - ANDROID_SENSOR_OPAQUE_RAW_SIZE
 *     - ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
 *
 * 3.5: Minor revisions to support session parameters and logical multi camera:
 *
 *   - Add ANDROID_REQUEST_AVAILABLE_SESSION_KEYS static metadata, which is
 *     optional for implementations that want to support session parameters. If support is
 *     needed, then Hal should populate the list with all available capture request keys
 *     that can cause severe processing delays when modified by client. Typical examples
 *     include parameters that require time-consuming HW re-configuration or internal camera
 *     pipeline update.
 *
 *   - Add a session parameter field to camera3_stream_configuration which can be populated
 *     by clients with initial values for the keys found in ANDROID_REQUEST_AVAILABLE_SESSION_KEYS.
 *
 *   - Metadata additions for logical multi camera capability:
 *     - ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
 *     - ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
 *     - ANDROID_LOGICAL_MULTI_CAMERA_SYNC_TYPE
 *
 *   - Add physical camera id field in camera3_stream, so that for a logical
 *     multi camera, the application has the option to specify which physical camera
 *     a particular stream is configured on.
 *
 *   - Add physical camera id and settings field in camera3_capture_request, so that
 *     for a logical multi camera, the application has the option to specify individual
 *     settings for a particular physical device.
 *
 */

/**
 * S2. Startup and general expected operation sequence:
 *
 * 1. Framework calls camera_module_t->common.open(), which returns a
 *    hardware_device_t structure.
 *
 * 2. Framework inspects the hardware_device_t->version field, and instantiates
 *    the appropriate handler for that version of the camera hardware device. In
 *    case the version is CAMERA_DEVICE_API_VERSION_3_0, the device is cast to
 *    a camera3_device_t.
 *
 * 3. Framework calls camera3_device_t->ops->initialize() with the framework