Camera: Update camera docs about external device orientation

The orientation and facing of external devices cannot be used
for calculating the jpeg orientation. Clients should ignore
the reference code in this case.

Bug: 72261912
Test: Android compiles without errors
Change-Id: I05e85d00eed1454d43b8f648bc7debd1c2290f05

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 6719a54..fe037f8 100644 (file)
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -11442,8 +11442,8 @@ rotate the image data to match this orientation.<wbr/> When the image data is ro
 the thumbnail data will also be rotated.<wbr/></p>
 <p>Note that this orientation is relative to the orientation of the camera sensor,<wbr/> given
 by <a href="#static_android.sensor.orientation">android.<wbr/>sensor.<wbr/>orientation</a>.<wbr/></p>
-<p>To translate from the device orientation given by the Android sensor APIs,<wbr/> the following
-sample code may be used:</p>
+<p>To translate from the device orientation given by the Android sensor APIs for camera
+sensors which are not EXTERNAL,<wbr/> the following sample code may be used:</p>
 <pre><code>private int getJpegOrientation(CameraCharacteristics c,<wbr/> int deviceOrientation) {
     if (deviceOrientation == android.<wbr/>view.<wbr/>Orientation<wbr/>Event<wbr/>Listener.<wbr/>ORIENTATION_<wbr/>UNKNOWN) return 0;
     int sensorOrientation = c.<wbr/>get(Camera<wbr/>Characteristics.<wbr/>SENSOR_<wbr/>ORIENTATION);
@@ -11462,6 +11462,8 @@ sample code may be used:</p>
     return jpegOrientation;
 }
 </code></pre>
+<p>For EXTERNAL cameras the sensor orientation will always be set to 0 and the facing will
+also be set to EXTERNAL.<wbr/> The above code is not relevant in such case.<wbr/></p>
             </td>
           </tr>
 
@@ -12096,8 +12098,8 @@ rotate the image data to match this orientation.<wbr/> When the image data is ro
 the thumbnail data will also be rotated.<wbr/></p>
 <p>Note that this orientation is relative to the orientation of the camera sensor,<wbr/> given
 by <a href="#static_android.sensor.orientation">android.<wbr/>sensor.<wbr/>orientation</a>.<wbr/></p>
-<p>To translate from the device orientation given by the Android sensor APIs,<wbr/> the following
-sample code may be used:</p>
+<p>To translate from the device orientation given by the Android sensor APIs for camera
+sensors which are not EXTERNAL,<wbr/> the following sample code may be used:</p>
 <pre><code>private int getJpegOrientation(CameraCharacteristics c,<wbr/> int deviceOrientation) {
     if (deviceOrientation == android.<wbr/>view.<wbr/>Orientation<wbr/>Event<wbr/>Listener.<wbr/>ORIENTATION_<wbr/>UNKNOWN) return 0;
     int sensorOrientation = c.<wbr/>get(Camera<wbr/>Characteristics.<wbr/>SENSOR_<wbr/>ORIENTATION);
@@ -12116,6 +12118,8 @@ sample code may be used:</p>
     return jpegOrientation;
 }
 </code></pre>
+<p>For EXTERNAL cameras the sensor orientation will always be set to 0 and the facing will
+also be set to EXTERNAL.<wbr/> The above code is not relevant in such case.<wbr/></p>
             </td>
           </tr>
 

diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index e96a0a6..afaa23e 100644 (file)
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -3337,8 +3337,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           Note that this orientation is relative to the orientation of the camera sensor, given
           by android.sensor.orientation.
 
-          To translate from the device orientation given by the Android sensor APIs, the following
-          sample code may be used:
+          To translate from the device orientation given by the Android sensor APIs for camera
+          sensors which are not EXTERNAL, the following sample code may be used:
 
               private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) {
                   if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0;
@@ -3357,6 +3357,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
 
                   return jpegOrientation;
               }
+
+          For EXTERNAL cameras the sensor orientation will always be set to 0 and the facing will
+          also be set to EXTERNAL. The above code is not relevant in such case.
           </details>
           <tag id="BC" />
         </entry>