blob: 85b3f7dcb61a7d6dfad10da81ccc871efd31b781 [file] [log] [blame]
/*
* 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;
};