camera/device/3.4/types.hal - platform/hardware/interfaces - Git at Google

 /*
  * 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 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;
 };

 /**
  * New request templates, extending the @3.2 RequestTemplate
  */
 enum RequestTemplate : @3.2::RequestTemplate {
     /**
      * A template for selecting camera parameters that match TEMPLATE_PREVIEW as closely as
      * possible while improving the camera output for motion tracking use cases.
      *
      * This template is best used by applications that are frequently switching between motion
      * tracking use cases and regular still capture use cases, to minimize the IQ changes
      * when swapping use cases.
      *
      * This template is guaranteed to be supported on camera devices that support the
      * REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING capability.
      */
     MOTION_TRACKING_PREVIEW = 7,

     /**
      * A template for selecting camera parameters that maximize the quality of camera output for
      * motion tracking use cases.
      *
      * This template is best used by applications dedicated to motion tracking applications,
      * which aren't concerned about fast switches between motion tracking and other use cases.
      *
      * This template is guaranteed to be supported on camera devices that support the
      * REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING capability.
      */
     MOTION_TRACKING_BEST = 8,
 };

 /**
  * 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.
  */
 struct PhysicalCameraSetting {
     /**
      * If non-zero, read settings from request queue instead
      * (see ICameraDeviceSession.getCaptureRequestMetadataQueue).
      * If zero, read settings from .settings field.
      */
     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
      * 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 'phyCamId'.
      * In case the individual settings are empty or missing, Hal should fail the
      * request and return Status::ILLEGAL_ARGUMENT.
      */
     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.
  *
  */
 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'.
      */
     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.
      */
     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.
      *
      * The v3_2 CaptureResult metadata is read first from the FMQ, followed by
      * the physical cameras' metadata starting from index 0.
      */
     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;
 };
	/*
	* 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 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;
	};

	/**
	* New request templates, extending the @3.2 RequestTemplate
	*/
	enum RequestTemplate : @3.2::RequestTemplate {
	/**
	* A template for selecting camera parameters that match TEMPLATE_PREVIEW as closely as
	* possible while improving the camera output for motion tracking use cases.
	*
	* This template is best used by applications that are frequently switching between motion
	* tracking use cases and regular still capture use cases, to minimize the IQ changes
	* when swapping use cases.
	*
	* This template is guaranteed to be supported on camera devices that support the
	* REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING capability.
	*/
	MOTION_TRACKING_PREVIEW = 7,

	/**
	* A template for selecting camera parameters that maximize the quality of camera output for
	* motion tracking use cases.
	*
	* This template is best used by applications dedicated to motion tracking applications,
	* which aren't concerned about fast switches between motion tracking and other use cases.
	*
	* This template is guaranteed to be supported on camera devices that support the
	* REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING capability.
	*/
	MOTION_TRACKING_BEST = 8,
	};

	/**
	* 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.
	*/
	struct PhysicalCameraSetting {
	/**
	* If non-zero, read settings from request queue instead
	* (see ICameraDeviceSession.getCaptureRequestMetadataQueue).
	* If zero, read settings from .settings field.
	*/
	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
	* 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 'phyCamId'.
	* In case the individual settings are empty or missing, Hal should fail the
	* request and return Status::ILLEGAL_ARGUMENT.
	*/
	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.
	*
	*/
	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'.
	*/
	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.
	*/
	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.
	*
	* The v3_2 CaptureResult metadata is read first from the FMQ, followed by
	* the physical cameras' metadata starting from index 0.
	*/
	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;
	};