Add camera focus distances API.
Applications can use this API to estimate the distance
between the subject and the camera.
bug:1955650
Change-Id: Ie6c8ea4971759cab6c9bcdda2c5ceb5925791c27
diff --git a/api/current.xml b/api/current.xml
index 8104950..e17e31d 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -75570,6 +75570,19 @@
visibility="public"
>
</method>
+<method name="getFocusDistances"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="output" type="float[]">
+</parameter>
+</method>
<method name="getFocusMode"
return="java.lang.String"
abstract="false"
@@ -76492,6 +76505,39 @@
visibility="public"
>
</field>
+<field name="FOCUS_DISTANCE_FAR_INDEX"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="2"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="FOCUS_DISTANCE_NEAR_INDEX"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="0"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="FOCUS_DISTANCE_OPTIMAL_INDEX"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="1"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
<field name="FOCUS_MODE_AUTO"
type="java.lang.String"
transient="false"
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 6dc1a86..46c6cb8 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -762,6 +762,8 @@
private static final String KEY_ZOOM_RATIOS = "zoom-ratios";
private static final String KEY_ZOOM_SUPPORTED = "zoom-supported";
private static final String KEY_SMOOTH_ZOOM_SUPPORTED = "smooth-zoom-supported";
+ private static final String KEY_FOCUS_DISTANCES = "focus-distances";
+
// Parameter key suffix for supported values.
private static final String SUPPORTED_VALUES_SUFFIX = "-values";
@@ -874,10 +876,30 @@
*/
public static final String FOCUS_MODE_EDOF = "edof";
+ // Indices for focus distance array.
+ /**
+ * The array index of near focus distance for use with
+ * {@link #getFocusDistances(float[])}.
+ */
+ public static final int FOCUS_DISTANCE_NEAR_INDEX = 0;
+
+ /**
+ * The array index of optimal focus distance for use with
+ * {@link #getFocusDistances(float[])}.
+ */
+ public static final int FOCUS_DISTANCE_OPTIMAL_INDEX = 1;
+
+ /**
+ * The array index of far focus distance for use with
+ * {@link #getFocusDistances(float[])}.
+ */
+ public static final int FOCUS_DISTANCE_FAR_INDEX = 2;
+
/**
* Continuous focus mode. The camera continuously tries to focus. This
* is ideal for shooting video or shooting photo of moving object.
* Continuous focus starts when {@link #autoFocus(AutoFocusCallback)} is
+ * called. Continuous focus stops when {@link #cancelAutoFocus()} is
* called. AutoFocusCallback will be only called once as soon as the
* picture is in focus.
*/
@@ -1814,6 +1836,42 @@
return TRUE.equals(str);
}
+ /**
+ * Gets the distances from the camera to where an object appears to be
+ * in focus. The object is sharpest at the optimal focus distance. The
+ * depth of field is the far focus distance minus near focus distance.
+ *
+ * Focus distances may change after calling {@link
+ * #autoFocus(AutoFocusCallback)}, {@link #cancelAutoFocus}, or {@link
+ * #startPreview()}. Applications can call {@link #getParameters()}
+ * and this method anytime to get the latest focus distances. If the
+ * focus mode is FOCUS_MODE_EDOF, the values may be all 0, which means
+ * focus distance is not applicable. If the focus mode is
+ * FOCUS_MODE_CONTINUOUS and autofocus has started, focus distances may
+ * change from time to time.
+ *
+ * Far focus distance > optimal focus distance > near focus distance. If
+ * the far focus distance is infinity, the value will be
+ * Float.POSITIVE_INFINITY.
+ *
+ * @param output focus distances in meters. output must be a float
+ * array with three elements. Near focus distance, optimal focus
+ * distance, and far focus distance will be filled in the array.
+ * @see #NEAR_FOCUS_DISTANCE_INDEX
+ * @see #OPTIMAL_FOCUS_DISTANCE_INDEX
+ * @see #FAR_FOCUS_DISTANCE_INDEX
+ */
+ public void getFocusDistances(float[] output) {
+ if (output == null || output.length != 3) {
+ throw new IllegalArgumentException(
+ "output must be an float array with three elements.");
+ }
+ List<Float> distances = splitFloat(get(KEY_FOCUS_DISTANCES));
+ output[0] = distances.get(0);
+ output[1] = distances.get(1);
+ output[2] = distances.get(2);
+ }
+
// Splits a comma delimited string to an ArrayList of String.
// Return null if the passing string is null or the size is 0.
private ArrayList<String> split(String str) {
@@ -1843,6 +1901,21 @@
return substrings;
}
+ // Splits a comma delimited string to an ArrayList of Float.
+ // Return null if the passing string is null or the size is 0.
+ private ArrayList<Float> splitFloat(String str) {
+ if (str == null) return null;
+
+ StringTokenizer tokenizer = new StringTokenizer(str, ",");
+ ArrayList<Float> substrings = new ArrayList<Float>();
+ while (tokenizer.hasMoreElements()) {
+ String token = tokenizer.nextToken();
+ substrings.add(Float.parseFloat(token));
+ }
+ if (substrings.size() == 0) return null;
+ return substrings;
+ }
+
// Returns the value of a float parameter.
private float getFloat(String key, float defaultValue) {
try {
diff --git a/include/camera/CameraParameters.h b/include/camera/CameraParameters.h
index 979df9f..19b052b 100644
--- a/include/camera/CameraParameters.h
+++ b/include/camera/CameraParameters.h
@@ -221,9 +221,30 @@
// Example value: "true". Read only.
static const char KEY_SMOOTH_ZOOM_SUPPORTED[];
+ // The distances (in meters) from the camera to where an object appears to
+ // be in focus. The object is sharpest at the optimal focus distance. The
+ // depth of field is the far focus distance minus near focus distance.
+ //
+ // Applications can read this parameter anytime to get the latest focus
+ // distances. If the focus mode is FOCUS_MODE_EDOF, the values may be all
+ // 0, which means focus distance is not applicable. If the focus mode is
+ // FOCUS_MODE_CONTINUOUS and autofocus has started, focus distances may
+ // change from time to time.
+ //
+ // Far focus distance > optimal focus distance > near focus distance. If
+ // the far focus distance is infinity, the value should be "Infinity" (case
+ // sensitive). The format is three float values separated by commas. The
+ // first is near focus distance. The second is optimal focus distance. The
+ // third is far focus distance.
+ // Example value: "0.95,1.9,Infinity" or "0.049,0.05,0.051". Read only.
+ static const char KEY_FOCUS_DISTANCES[];
+
// Value for KEY_ZOOM_SUPPORTED or KEY_SMOOTH_ZOOM_SUPPORTED.
static const char TRUE[];
+ // Value for KEY_FOCUS_DISTANCES.
+ static const char INFINITY[];
+
// Values for white balance settings.
static const char WHITE_BALANCE_AUTO[];
static const char WHITE_BALANCE_INCANDESCENT[];
diff --git a/libs/camera/CameraParameters.cpp b/libs/camera/CameraParameters.cpp
index cfb7ba1..035fa9f 100644
--- a/libs/camera/CameraParameters.cpp
+++ b/libs/camera/CameraParameters.cpp
@@ -69,8 +69,10 @@
const char CameraParameters::KEY_ZOOM_RATIOS[] = "zoom-ratios";
const char CameraParameters::KEY_ZOOM_SUPPORTED[] = "zoom-supported";
const char CameraParameters::KEY_SMOOTH_ZOOM_SUPPORTED[] = "smooth-zoom-supported";
+const char CameraParameters::KEY_FOCUS_DISTANCES[] = "focus-distances";
const char CameraParameters::TRUE[] = "true";
+const char CameraParameters::INFINITY[] = "Infinity";
// Values for white balance settings.
const char CameraParameters::WHITE_BALANCE_AUTO[] = "auto";
