camera2-portability: Make factory offer choice of backing API

This allows apps using the library to decide whether to jump to the new API.
Users of the library may choose to use the Camera class, the camera2 API, or
have the choice made automatically based on the device's API level. The choice
may also be globally overridden by means of a system property.

Bug: 16875535
Change-Id: I92e4be96fbd04057be61ceb8a0c58935770022f6

1 files changed, 122 insertions, 14 deletions

diff --git a/camera2/portability/src/com/android/ex/camera2/portability/CameraAgentFactory.java b/camera2/portability/src/com/android/ex/camera2/portability/CameraAgentFactory.java
index 00dc280..77ad0c3 100644
--- a/camera2/portability/src/com/android/ex/camera2/portability/CameraAgentFactory.java
+++ b/camera2/portability/src/com/android/ex/camera2/portability/CameraAgentFactory.java
@@ -17,42 +17,150 @@
 package com.android.ex.camera2.portability;
 
 import android.content.Context;
+import android.os.Build;
+
+import com.android.ex.camera2.portability.debug.Log;
+import com.android.ex.camera2.portability.util.SystemProperties;
 
 /**
  * A factory class for {@link CameraAgent}.
+ *
+ * <p>The choice of framework API to use can be made automatically based on the
+ * system API level, explicitly forced by the client app, or overridden entirely
+ * by setting the system property com.camera2.portability.fwk_api to 1 or 2.</p>
  */
 public class CameraAgentFactory {
+    private static final Log.Tag TAG = new Log.Tag("CamAgntFact");
+
+    /** Android release replacing the Camera class with the camera2 package. */
+    private static final int FIRST_SDK_WITH_API_2 = 21;
+
+    // The debugging override, which overrides *all* API level selections if set
+    // to API_LEVEL_OVERRIDE_API{1,2}; otherwise, this has no effect. Note that
+    // we check this once when the library is first loaded so that #recycle()
+    // doesn't try to clean up the wrong type of CameraAgent.
+    private static final String API_LEVEL_OVERRIDE_KEY = "camera2.portability.force_api";
+    private static final String API_LEVEL_OVERRIDE_DEFAULT = "0";
+    private static final String API_LEVEL_OVERRIDE_API1 = "1";
+    private static final String API_LEVEL_OVERRIDE_API2 = "2";
+    private static final String API_LEVEL_OVERRIDE_VALUE =
+            SystemProperties.get(API_LEVEL_OVERRIDE_KEY, API_LEVEL_OVERRIDE_DEFAULT);
 
     private static CameraAgent sAndroidCameraAgent;
+    private static CameraAgent sAndroidCamera2Agent;
     private static int sAndroidCameraAgentClientCount;
+    private static int sAndroidCamera2AgentClientCount;
 
     /**
-     * Returns the android camera implementation of {@link com.android.camera.cameradevice.CameraAgent}.
+     * Used to indicate which camera framework should be used.
+     */
+    public static enum CameraApi {
+        /** Automatically select based on the device's SDK level. */
+        AUTO,
+
+        /** Use the {@link android.hardware.Camera} class. */
+        API_1,
+
+        /** Use the {@link android.hardware.camera2} package. */
+        API_2
+    };
+
+    private static CameraApi highestSupportedApi() {
+        // TODO: Check SDK_INT instead of RELEASE before L launch
+        if (Build.VERSION.SDK_INT >= FIRST_SDK_WITH_API_2 || Build.VERSION.CODENAME.equals("L")) {
+            return CameraApi.API_2;
+        } else {
+            return CameraApi.API_1;
+        }
+    }
+
+    private static CameraApi validateApiChoice(CameraApi choice) {
+        if (API_LEVEL_OVERRIDE_VALUE.equals(API_LEVEL_OVERRIDE_API1)) {
+            Log.d(TAG, "API level overridden by system property: forced to 1");
+            return CameraApi.API_1;
+        } else if (API_LEVEL_OVERRIDE_VALUE.equals(API_LEVEL_OVERRIDE_API2)) {
+            Log.d(TAG, "API level overridden by system property: forced to 2");
+            return CameraApi.API_2;
+        }
+
+        if (choice == null) {
+            Log.w(TAG, "null API level request, so assuming AUTO");
+            choice = CameraApi.AUTO;
+        }
+        if (choice == CameraApi.AUTO) {
+            choice = highestSupportedApi();
+        }
+
+        return choice;
+    }
+
+    /**
+     * Returns the android camera implementation of
+     * {@link com.android.camera.cameradevice.CameraAgent}.
+     *
+     * <p>To clean up the resources allocated by this call, be sure to invoke
+     * {@link #recycle(boolean)} with the same {@code api} value provided
+     * here.</p>
      *
+     * @param context The application context.
+     * @param api Which camera framework to use.
      * @return The {@link CameraAgent} to control the camera device.
+     *
+     * @throws UnsupportedOperationException If {@code CameraApi.API_2} was
+     *                                       requested on an unsupported device.
      */
-    public static synchronized CameraAgent getAndroidCameraAgent(Context context) {
-        if (sAndroidCameraAgent == null) {
-            if (false) {
-                sAndroidCameraAgent = new AndroidCamera2AgentImpl(context);
-            } else {
+    public static synchronized CameraAgent getAndroidCameraAgent(Context context, CameraApi api) {
+        api = validateApiChoice(api);
+
+        if (api == CameraApi.API_1) {
+            if (sAndroidCameraAgent == null) {
                 sAndroidCameraAgent = new AndroidCameraAgentImpl();
+                sAndroidCameraAgentClientCount = 1;
+            } else {
+                ++sAndroidCameraAgentClientCount;
             }
-            sAndroidCameraAgentClientCount = 1;
-        } else {
-            ++sAndroidCameraAgentClientCount;
+            return sAndroidCameraAgent;
+        } else { // API_2
+            if (highestSupportedApi() == CameraApi.API_1) {
+                throw new UnsupportedOperationException("Camera API_2 unavailable on this device");
+            }
+
+            if (sAndroidCamera2Agent == null) {
+                sAndroidCamera2Agent = new AndroidCamera2AgentImpl(context);
+                sAndroidCamera2AgentClientCount = 1;
+            } else {
+                ++sAndroidCamera2AgentClientCount;
+            }
+            return sAndroidCamera2Agent;
         }
-        return sAndroidCameraAgent;
     }
 
     /**
      * Recycles the resources. Always call this method when the activity is
      * stopped.
+     *
+     * @param api Which camera framework handle to recycle.
+     *
+     * @throws UnsupportedOperationException If {@code CameraApi.API_2} was
+     *                                       requested on an unsupported device.
      */
-    public static synchronized void recycle() {
-        if (--sAndroidCameraAgentClientCount == 0 && sAndroidCameraAgent != null) {
-            sAndroidCameraAgent.recycle();
-            sAndroidCameraAgent = null;
+    public static synchronized void recycle(CameraApi api) {
+        api = validateApiChoice(api);
+
+        if (api == CameraApi.API_1) {
+            if (--sAndroidCameraAgentClientCount == 0 && sAndroidCameraAgent != null) {
+                sAndroidCameraAgent.recycle();
+                sAndroidCameraAgent = null;
+            }
+        } else { // API_2
+            if (highestSupportedApi() == CameraApi.API_1) {
+                throw new UnsupportedOperationException("Camera API_2 unavailable on this device");
+            }
+
+            if (--sAndroidCamera2AgentClientCount == 0 && sAndroidCamera2Agent != null) {
+                sAndroidCamera2Agent.recycle();
+                sAndroidCamera2Agent = null;
+            }
         }
     }
 }