From a20f4c2648d7c597e3178978d17eb5894ef2b2b9 Mon Sep 17 00:00:00 2001
From: Ruben Brunk <rubenbrunk@google.com>
Date: Fri, 17 Jan 2014 15:21:13 -0800
Subject: [PATCH] camera3: focalLength tag frameworks/base changes.

Change-Id: I59614223ae65e602f3461029cb4b8848fb22950e
---
 .../android/hardware/camera2/CameraCharacteristics.java  | 13 ++++++++-----
 core/java/android/hardware/camera2/CaptureRequest.java   | 16 ++++++++++++++--
 core/java/android/hardware/camera2/CaptureResult.java    | 16 ++++++++++++++--
 3 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 8be50499c58b..a5d1ec5cd296 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -297,11 +297,14 @@ public final class CameraCharacteristics extends CameraMetadata {
             new Key<float[]>("android.lens.info.availableFilterDensities", float[].class);
 
     /**
-     * <p>If fitted with optical zoom, what focal
-     * lengths are available. If not, the static focal
-     * length</p>
-     * <p>If optical zoom not supported, only one value
-     * should be reported</p>
+     * <p>The available focal lengths for this device for use with
+     * {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}.</p>
+     * <p>If optical zoom is not supported, this will only report
+     * a single value corresponding to the static focal length of the
+     * device. Otherwise, this will report every focal length supported
+     * by the device.</p>
+     *
+     * @see CaptureRequest#LENS_FOCAL_LENGTH
      */
     public static final Key<float[]> LENS_INFO_AVAILABLE_FOCAL_LENGTHS =
             new Key<float[]>("android.lens.info.availableFocalLengths", float[].class);
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index cd35de4fe633..13a6cb6dfc1d 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -929,8 +929,20 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
             new Key<Float>("android.lens.filterDensity", float.class);
 
     /**
-     * <p>Lens optical zoom setting</p>
-     * <p>Will not be supported on most devices.</p>
+     * <p>The current lens focal length; used for optical zoom.</p>
+     * <p>This setting controls the physical focal length of the camera
+     * device's lens. Changing the focal length changes the field of
+     * view of the camera device, and is usually used for optical zoom.</p>
+     * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this
+     * setting won't be applied instantaneously, and it may take several
+     * frames before the lens can move to the requested focal length.
+     * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
+     * be set to MOVING.</p>
+     * <p>This is expected not to be supported on most devices.</p>
+     *
+     * @see CaptureRequest#LENS_APERTURE
+     * @see CaptureRequest#LENS_FOCUS_DISTANCE
+     * @see CaptureResult#LENS_STATE
      */
     public static final Key<Float> LENS_FOCAL_LENGTH =
             new Key<Float>("android.lens.focalLength", float.class);
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index aa12d5e8c52c..999014288842 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -1097,8 +1097,20 @@ public final class CaptureResult extends CameraMetadata {
             new Key<Float>("android.lens.filterDensity", float.class);
 
     /**
-     * <p>Lens optical zoom setting</p>
-     * <p>Will not be supported on most devices.</p>
+     * <p>The current lens focal length; used for optical zoom.</p>
+     * <p>This setting controls the physical focal length of the camera
+     * device's lens. Changing the focal length changes the field of
+     * view of the camera device, and is usually used for optical zoom.</p>
+     * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this
+     * setting won't be applied instantaneously, and it may take several
+     * frames before the lens can move to the requested focal length.
+     * While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
+     * be set to MOVING.</p>
+     * <p>This is expected not to be supported on most devices.</p>
+     *
+     * @see CaptureRequest#LENS_APERTURE
+     * @see CaptureRequest#LENS_FOCUS_DISTANCE
+     * @see CaptureResult#LENS_STATE
      */
     public static final Key<Float> LENS_FOCAL_LENGTH =
             new Key<Float>("android.lens.focalLength", float.class);
-- 
2.11.0