Camera: Clarify camera ID selection logic for logical camera

- Clarify the assumption camera app can make on camera ids.
- Document that camera service only advertises one camera id out of every
logical camera id combination for API1.

Test: Build
Bug: 80075565
Change-Id: Idc3c600983ef36f24cdc7f4ca0f25e41451ff8ab

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index f64b38a..4b4622f 100644 (file)
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -17088,6 +17088,10 @@ results for use cases such as image stabilization or augmented reality.<wbr/></p
                     <span class="entry_type_enum_optional">[optional]</span>
                     <span class="entry_type_enum_notes"><p>The camera device is a logical camera backed by two or more physical cameras that are
 also exposed to the application.<wbr/></p>
+<p>Camera application shouldn't assume that there are at most 1 rear camera and 1 front
+camera in the system.<wbr/> For an application that switches between front and back cameras,<wbr/>
+the recommendation is to switch between the first rear camera and the first front
+camera in the list of supported camera devices.<wbr/></p>
 <p>This capability requires the camera device to support the following:</p>
 <ul>
 <li>This camera device must list the following static metadata entries in <a href="https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics.html">CameraCharacteristics</a>:<ul>
@@ -17220,6 +17224,18 @@ DEPTH).<wbr/></p>
 <p>For a camera device with LOGICAL_<wbr/>MULTI_<wbr/>CAMERA capability,<wbr/> it should operate in the
 same way as a physical camera device based on its hardware level and capabilities.<wbr/>
 It's recommended that its feature set is superset of that of individual physical cameras.<wbr/></p>
+<ul>
+<li>
+<p>In camera1 API,<wbr/> to maintain application compatibility,<wbr/> for each {logical_<wbr/>camera_<wbr/>id,<wbr/>
+physical_<wbr/>camera_<wbr/>1_<wbr/>id,<wbr/> physical_<wbr/>camera_<wbr/>2_<wbr/>id,<wbr/> ...<wbr/>} combination,<wbr/> where logical_<wbr/>camera_<wbr/>id
+is composed of physical_<wbr/>camera_<wbr/>N_<wbr/>id,<wbr/> camera framework will only advertise one camera id
+(within the combination) that is frontmost in the HAL published camera id list.<wbr/></p>
+</li>
+<li>
+<p>Camera HAL is strongly recommended to advertise camera devices with best feature,<wbr/>
+power,<wbr/> performance,<wbr/> and latency tradeoffs at the front of the camera id list.<wbr/></p>
+</li>
+</ul>
 <p>For MONOCHROME,<wbr/> the camera device must also advertise BACKWARD_<wbr/>COMPATIBLE capability,<wbr/> and
 it is exclusive of both RAW and MANUAL_<wbr/>POST_<wbr/>PROCESSING capabilities:</p>
 <ul>

diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index 55f8481..9718762 100644 (file)
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -5210,6 +5210,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               The camera device is a logical camera backed by two or more physical cameras that are
               also exposed to the application.
 
+              Camera application shouldn't assume that there are at most 1 rear camera and 1 front
+              camera in the system. For an application that switches between front and back cameras,
+              the recommendation is to switch between the first rear camera and the first front
+              camera in the list of supported camera devices.
+
               This capability requires the camera device to support the following:
 
               * This camera device must list the following static metadata entries in {@link
@@ -5325,6 +5330,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           same way as a physical camera device based on its hardware level and capabilities.
           It's recommended that its feature set is superset of that of individual physical cameras.
 
+          * In camera1 API, to maintain application compatibility, for each {logical_camera_id,
+          physical_camera_1_id, physical_camera_2_id, ...} combination, where logical_camera_id
+          is composed of physical_camera_N_id, camera framework will only advertise one camera id
+          (within the combination) that is frontmost in the HAL published camera id list.
+
+          * Camera HAL is strongly recommended to advertise camera devices with best feature,
+          power, performance, and latency tradeoffs at the front of the camera id list.
+
           For MONOCHROME, the camera device must also advertise BACKWARD_COMPATIBLE capability, and
           it is exclusive of both RAW and MANUAL_POST_PROCESSING capabilities: