Camera: Improve logical camera RAW capture docs
- Clarify raw capture behavior for logical camera with backward
compatible approach and MultiResolutionImageReader.
- Some logical camera devices may have identical physical cameras with
different focal length. Allow such logical camera to switch physical
cameras when outputing raw.
Test: ZoomCaptureTest CTS test
Bug: 182217158
Change-Id: I393a2129a14f001615e99a729d070bebb194d8ef
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index fc3f33b..6b735d5 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -18736,13 +18736,27 @@
camera's crop region is set to maximum size,<wbr/> the FOV of the physical streams for the
ultrawide lens will be the same as the logical stream,<wbr/> by making the crop region
smaller than its active array size to compensate for the smaller focal length.<wbr/></p>
-<p>Even if the underlying physical cameras have different RAW characteristics (such as
-size or CFA pattern),<wbr/> a logical camera can still advertise RAW capability.<wbr/> In this
-case,<wbr/> when the application configures a RAW stream,<wbr/> the camera device will make sure
-the active physical camera will remain active to ensure consistent RAW output
-behavior,<wbr/> and not switch to other physical cameras.<wbr/></p>
+<p>There are two ways for the application to capture RAW images from a logical camera
+with RAW capability:</p>
+<ul>
+<li>Because the underlying physical cameras may have different RAW capabilities (such
+as resolution or CFA pattern),<wbr/> to maintain backward compatibility,<wbr/> when a RAW stream
+is configured,<wbr/> the camera device makes sure the default active physical camera remains
+active and does not switch to other physical cameras.<wbr/> (One exception is that,<wbr/> if the
+logical camera consists of identical image sensors and advertises multiple focalLength
+due to different lenses,<wbr/> the camera device may generate RAW images from different
+physical cameras based on the focalLength being set by the application.<wbr/>) This
+backward-compatible approach usually results in loss of optical zoom,<wbr/> to telephoto
+lens or to ultrawide lens.<wbr/></li>
+<li>Alternatively,<wbr/> to take advantage of the full zoomRatio range of the logical camera,<wbr/>
+the application should use <a href="https://developer.android.com/reference/android/hardware/camera2/MultiResolutionImageReader.html">MultiResolutionImageReader</a>
+to capture RAW images from the currently active physical camera.<wbr/> Because different
+physical camera may have different RAW characteristics,<wbr/> the application needs to use
+the characteristics and result metadata of the active physical camera for the
+relevant RAW metadata.<wbr/></li>
+</ul>
<p>The capture request and result metadata tags required for backward compatible camera
-functionalities will be solely based on the logical camera capabiltity.<wbr/> On the other
+functionalities will be solely based on the logical camera capability.<wbr/> On the other
hand,<wbr/> the use of manual capture controls (sensor or post-processing) with a
logical camera may result in unexpected behavior when the HAL decides to switch
between physical cameras with different characteristics under the hood.<wbr/> For example,<wbr/>
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index 34d4c1f..672fcee 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -5934,14 +5934,27 @@
ultrawide lens will be the same as the logical stream, by making the crop region
smaller than its active array size to compensate for the smaller focal length.
- Even if the underlying physical cameras have different RAW characteristics (such as
- size or CFA pattern), a logical camera can still advertise RAW capability. In this
- case, when the application configures a RAW stream, the camera device will make sure
- the active physical camera will remain active to ensure consistent RAW output
- behavior, and not switch to other physical cameras.
+ There are two ways for the application to capture RAW images from a logical camera
+ with RAW capability:
+
+ * Because the underlying physical cameras may have different RAW capabilities (such
+ as resolution or CFA pattern), to maintain backward compatibility, when a RAW stream
+ is configured, the camera device makes sure the default active physical camera remains
+ active and does not switch to other physical cameras. (One exception is that, if the
+ logical camera consists of identical image sensors and advertises multiple focalLength
+ due to different lenses, the camera device may generate RAW images from different
+ physical cameras based on the focalLength being set by the application.) This
+ backward-compatible approach usually results in loss of optical zoom, to telephoto
+ lens or to ultrawide lens.
+ * Alternatively, to take advantage of the full zoomRatio range of the logical camera,
+ the application should use {@link android.hardware.camera2.MultiResolutionImageReader}
+ to capture RAW images from the currently active physical camera. Because different
+ physical camera may have different RAW characteristics, the application needs to use
+ the characteristics and result metadata of the active physical camera for the
+ relevant RAW metadata.
The capture request and result metadata tags required for backward compatible camera
- functionalities will be solely based on the logical camera capabiltity. On the other
+ functionalities will be solely based on the logical camera capability. On the other
hand, the use of manual capture controls (sensor or post-processing) with a
logical camera may result in unexpected behavior when the HAL decides to switch
between physical cameras with different characteristics under the hood. For example,