Merge "camera2: Add key enumeration functionality to CameraMetadata" into klp-dev

api/current.txt

@@ -10862,6 +10862,7 @@ package android.hardware.camera2 {
 
   public abstract class CameraMetadata {
     method public abstract T get(android.hardware.camera2.CameraMetadata.Key<T>);
+    method public java.util.List<android.hardware.camera2.CameraMetadata.Key<?>> getKeys();
     field public static final int COLOR_CORRECTION_MODE_FAST = 1; // 0x1
     field public static final int COLOR_CORRECTION_MODE_HIGH_QUALITY = 2; // 0x2
     field public static final int COLOR_CORRECTION_MODE_TRANSFORM_MATRIX = 0; // 0x0
@@ -10987,6 +10988,8 @@ package android.hardware.camera2 {
 
   public final class CameraProperties extends android.hardware.camera2.CameraMetadata {
     method public T get(android.hardware.camera2.CameraMetadata.Key<T>);
+    method public java.util.List<android.hardware.camera2.CameraMetadata.Key<?>> getAvailableCaptureRequestKeys();
+    method public java.util.List<android.hardware.camera2.CameraMetadata.Key<?>> getAvailableCaptureResultKeys();
     field public static final android.hardware.camera2.CameraMetadata.Key CONTROL_AE_AVAILABLE_ANTIBANDING_MODES;
     field public static final android.hardware.camera2.CameraMetadata.Key CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES;
     field public static final android.hardware.camera2.CameraMetadata.Key CONTROL_AE_COMPENSATION_RANGE;

core/java/android/hardware/camera2/CameraMetadata.java

@@ -18,12 +18,25 @@ package android.hardware.camera2;
 
 import android.hardware.camera2.impl.CameraMetadataNative;
 
+import java.lang.reflect.Field;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
 /**
  * The base class for camera controls and information.
  *
+ * <p>
  * This class defines the basic key/value map used for querying for camera
  * characteristics or capture results, and for setting camera request
  * parameters.
+ * </p>
+ *
+ * <p>
+ * All instances of CameraMetadata are immutable. The list of keys with {@link #getKeys()}
+ * never changes, nor do the values returned by any key with {@link #get} throughout
+ * the lifetime of the object.
+ * </p>
  *
  * @see CameraDevice
  * @see CameraManager
@@ -38,9 +51,14 @@ public abstract class CameraMetadata {
     }
 
     /**
-     * Get a camera metadata field value. The field definitions can be
+     * Get a camera metadata field value.
+     *
+     * <p>The field definitions can be
      * found in {@link CameraProperties}, {@link CaptureResult}, and
-     * {@link CaptureRequest}.
+     * {@link CaptureRequest}.</p>
+     *
+     * <p>Querying the value for the same key more than once will return a value
+     * which is equal to the previous queried value.</p>
      *
      * @throws IllegalArgumentException if the key was not valid
      *
@@ -49,6 +67,54 @@ public abstract class CameraMetadata {
      */
     public abstract <T> T get(Key<T> key);
 
+    /**
+     * Returns a list of the keys contained in this map.
+     *
+     * <p>The list returned is not modifiable, so any attempts to modify it will throw
+     * a {@code UnsupportedOperationException}.</p>
+     *
+     * <p>All values retrieved by a key from this list with {@link #get} are guaranteed to be
+     * non-{@code null}. Each key is only listed once in the list. The order of the keys
+     * is undefined.</p>
+     *
+     * @return List of the keys contained in this map.
+     */
+    public List<Key<?>> getKeys() {
+        return Collections.unmodifiableList(getKeysStatic(this.getClass(), this));
+    }
+
+    /**
+     * Return a list of all the Key<?> that are declared as a field inside of the class
+     * {@code type}.
+     *
+     * <p>
+     * Optionally, if {@code instance} is not null, then filter out any keys with null values.
+     * </p>
+     */
+    /*package*/ static ArrayList<Key<?>> getKeysStatic(Class<? extends CameraMetadata> type,
+            CameraMetadata instance) {
+        ArrayList<Key<?>> keyList = new ArrayList<Key<?>>();
+
+        Field[] fields = type.getDeclaredFields();
+        for (Field field : fields) {
+            if (field.getDeclaringClass().isAssignableFrom(Key.class)) {
+                Key<?> key;
+                try {
+                    key = (Key<?>) field.get(instance);
+                } catch (IllegalAccessException e) {
+                    throw new AssertionError("Can't get IllegalAccessException", e);
+                } catch (IllegalArgumentException e) {
+                    throw new AssertionError("Can't get IllegalArgumentException", e);
+                }
+                if (instance == null || instance.get(key) != null) {
+                    keyList.add(key);
+                }
+            }
+        }
+
+        return keyList;
+    }
+
     public static class Key<T> {
 
         private boolean mHasTag;

core/java/android/hardware/camera2/CameraProperties.java

@@ -18,6 +18,9 @@ package android.hardware.camera2;
 
 import android.hardware.camera2.impl.CameraMetadataNative;
 
+import java.util.Collections;
+import java.util.List;
+
 /**
  * <p>The properties describing a
  * {@link CameraDevice CameraDevice}.</p>
@@ -32,6 +35,8 @@ import android.hardware.camera2.impl.CameraMetadataNative;
 public final class CameraProperties extends CameraMetadata {
 
     private final CameraMetadataNative mProperties;
+    private List<Key<?>> mAvailableRequestKeys;
+    private List<Key<?>> mAvailableResultKeys;
 
     /**
      * Takes ownership of the passed-in properties object
@@ -46,6 +51,75 @@ public final class CameraProperties extends CameraMetadata {
         return mProperties.get(key);
     }
 
+    /**
+     * Returns the list of keys supported by this {@link CameraDevice} for querying
+     * with a {@link CaptureRequest}.
+     *
+     * <p>The list returned is not modifiable, so any attempts to modify it will throw
+     * a {@code UnsupportedOperationException}.</p>
+     *
+     * <p>Each key is only listed once in the list. The order of the keys is undefined.</p>
+     *
+     * <p>Note that there is no {@code getAvailableCameraPropertiesKeys()} -- use
+     * {@link #getKeys()} instead.</p>
+     *
+     * @return List of keys supported by this CameraDevice for CaptureRequests.
+     */
+    public List<Key<?>> getAvailableCaptureRequestKeys() {
+        if (mAvailableRequestKeys == null) {
+            mAvailableRequestKeys = getAvailableKeyList(CaptureRequest.class);
+        }
+        return mAvailableRequestKeys;
+    }
+
+    /**
+     * Returns the list of keys supported by this {@link CameraDevice} for querying
+     * with a {@link CaptureResult}.
+     *
+     * <p>The list returned is not modifiable, so any attempts to modify it will throw
+     * a {@code UnsupportedOperationException}.</p>
+     *
+     * <p>Each key is only listed once in the list. The order of the keys is undefined.</p>
+     *
+     * <p>Note that there is no {@code getAvailableCameraPropertiesKeys()} -- use
+     * {@link #getKeys()} instead.</p>
+     *
+     * @return List of keys supported by this CameraDevice for CaptureResults.
+     */
+    public List<Key<?>> getAvailableCaptureResultKeys() {
+        if (mAvailableResultKeys == null) {
+            mAvailableResultKeys = getAvailableKeyList(CaptureResult.class);
+        }
+        return mAvailableResultKeys;
+    }
+
+    /**
+     * Returns the list of keys supported by this {@link CameraDevice} by metadataClass.
+     *
+     * <p>The list returned is not modifiable, so any attempts to modify it will throw
+     * a {@code UnsupportedOperationException}.</p>
+     *
+     * <p>Each key is only listed once in the list. The order of the keys is undefined.</p>
+     *
+     * @param metadataClass The subclass of CameraMetadata that you want to get the keys for.
+     *
+     * @return List of keys supported by this CameraDevice for metadataClass.
+     *
+     * @throws IllegalArgumentException if metadataClass is not a subclass of CameraMetadata
+     */
+    private <T extends CameraMetadata> List<Key<?>> getAvailableKeyList(Class<T> metadataClass) {
+
+        if (metadataClass.equals(CameraMetadata.class)) {
+            throw new AssertionError(
+                    "metadataClass must be a strict subclass of CameraMetadata");
+        } else if (!CameraMetadata.class.isAssignableFrom(metadataClass)) {
+            throw new AssertionError(
+                    "metadataClass must be a subclass of CameraMetadata");
+        }
+
+        return Collections.unmodifiableList(getKeysStatic(metadataClass, /*instance*/null));
+    }
+
     /*@O~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
      * The key entries below this point are generated from metadata
      * definitions in /system/media/camera/docs. Do not modify by hand or

core/java/android/hardware/camera2/CaptureRequest.java

@@ -176,7 +176,7 @@ public final class CaptureRequest extends CameraMetadata implements Parcelable {
      */
     public final static class Builder {
 
-        private CaptureRequest mRequest;
+        private final CaptureRequest mRequest;
 
         /**
          * Initialize the builder using the template; the request takes

core/java/android/hardware/camera2/impl/CameraMetadataNative.java

@@ -27,7 +27,6 @@ import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 import java.util.ArrayList;
 import java.util.HashMap;
-import java.util.Map;
 
 /**
  * Implementation of camera metadata marshal/unmarshal across Binder to