From: Emilian Peev <epeev@google.com>
Date: Wed, 28 Mar 2018 10:17:14 +0000 (+0100)
Subject: Camera: Update camera docs about external device orientation
X-Git-Tag: android-x86-9.0-r1~13^2^2
X-Git-Url: http://git.osdn.net/view?p=android-x86%2Fsystem-media.git;a=commitdiff_plain;h=fb4387286b865a8fb1f3591b5256f5cf1b088ff6

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 6719a54c..fe037f8a 100644
--- 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 e96a0a6d..afaa23ee 100644
--- 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>