Camera: Document 3.4 metadata selection logic.
Bug: 119575429
Test: Ensure everything still builds.
Change-Id: I6500ab06b8c392310009ecfa0570000742fd069c
diff --git a/camera/device/3.4/types.hal b/camera/device/3.4/types.hal
index 8ee826b..85b3f7d 100644
--- a/camera/device/3.4/types.hal
+++ b/camera/device/3.4/types.hal
@@ -208,8 +208,70 @@
* structure asynchronously to the framework, using the processCaptureResult()
* callback.
*
- * Identical to @3.2::CaptureRequest, except that it contains @3.4::physCamSettings vector.
+ * 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 {
/**
diff --git a/current.txt b/current.txt
index beafcf0..eb73b57 100644
--- a/current.txt
+++ b/current.txt
@@ -388,7 +388,7 @@
2a55e224aa9bc62c0387cd85ad3c97e33f0c33a4e1489cbae86b2523e6f9df35 android.hardware.camera.device@3.2::ICameraDevice
8caf9104dc6885852c0b117d853dd93f6d4b61a0a365138295eb8bcd41b36423 android.hardware.camera.device@3.2::ICameraDeviceSession
684702a60deef03a1e8093961dc0a18c555c857ad5a77ba7340b0635ae01eb70 android.hardware.camera.device@3.4::ICameraDeviceSession
-e96190f635b8458b92525bd6e040fec4ccbac22fdd4bc7274a9794ab976362f7 android.hardware.camera.device@3.4::types
+f8a19622cb0cc890913b1ef3e32b675ffb26089a09e02fef4056ebad324d2b5d android.hardware.camera.device@3.4::types
291638a1b6d4e63283e9e722ab5049d9351717ffa2b66162124f84d1aa7c2835 android.hardware.camera.metadata@3.2::types
8a075cf3a17fe99c6d23415a3e9a65612f1fee73ee052a3a8a0ca5b8877395a4 android.hardware.camera.metadata@3.3::types
da33234403ff5d60f3473711917b9948e6484a4260b5247acdafb111193a9de2 android.hardware.configstore@1.0::ISurfaceFlingerConfigs