take APIs refactoring, removing deprecated

MIGRATION.md

@@ -2,4 +2,9 @@
 
 - JpegQuality: both cameraJpegQuality and setJpegQuality() have been removed, because
   they were working only with specific setups. We'll use the default quality provided
-  by the camera engine.
+  by the camera engine.
+- capturePicture: renamed to takePicture()
+- captureSnapshot: renamed to takePictureSnapshot()
+- startCapturingVideo: renamed to takeVideo(). Signature changed from long to int.
+- getSnapshotSize(): removed. The size of snapshots (pictures and videos) is equal to
+  the preview size as returned by getPreviewSize().

cameraview/src/androidTest/java/com/otaliastudios/cameraview/CameraViewCallbacksTest.java

@@ -269,7 +269,7 @@ public class CameraViewCallbacksTest extends BaseTest {
 
         // Create fake JPEG array and trigger the process.
         if (jpeg) {
-            camera.mCameraCallbacks.processImage(mockJpeg(imageDim[0], imageDim[1]), true, false);
+            camera.mCameraCallbacks.processPicture(mockJpeg(imageDim[0], imageDim[1]), true, false);
         } else {
             camera.mCameraCallbacks.processSnapshot(mockYuv(imageDim[0], imageDim[1]), true, false);
         }

cameraview/src/androidTest/java/com/otaliastudios/cameraview/CameraViewTest.java

@@ -79,7 +79,6 @@ public class CameraViewTest extends BaseTest {
         assertNull(cameraView.getExtraProperties());
         assertNull(cameraView.getPreviewSize());
         assertNull(cameraView.getPictureSize());
-        assertNull(cameraView.getSnapshotSize());
     }
 
     @Test

cameraview/src/androidTest/java/com/otaliastudios/cameraview/IntegrationTest.java

@@ -5,7 +5,6 @@ import android.graphics.Bitmap;
 import android.graphics.PointF;
 import android.hardware.Camera;
 import android.os.Build;
-import android.os.Handler;
 import android.support.test.filters.MediumTest;
 import android.support.test.rule.ActivityTestRule;
 import android.support.test.runner.AndroidJUnit4;
@@ -90,7 +89,7 @@ public class IntegrationTest extends BaseTest {
 
     @After
     public void tearDown() throws Exception {
-        camera.stopCapturingVideo();
+        camera.stopVideo();
         camera.destroy();
         WorkerHandler.destroy();
     }
@@ -150,7 +149,7 @@ public class IntegrationTest extends BaseTest {
 
     private void waitForVideoStart() {
         controller.mStartVideoTask.listen();
-        camera.startCapturingVideo(null);
+        camera.takeVideo(null);
         controller.mStartVideoTask.await(400);
     }
 
@@ -432,7 +431,7 @@ public class IntegrationTest extends BaseTest {
 
     //endregion
 
-    //region test startVideo
+    //region test takeVideo
 
     @Test(expected = RuntimeException.class)
     public void testStartVideo_whileInPictureMode() throws Throwable {
@@ -452,7 +451,7 @@ public class IntegrationTest extends BaseTest {
         // as documented. This works locally though.
         camera.setSessionType(SessionType.VIDEO);
         waitForOpen(true);
-        camera.startCapturingVideo(null, 4000);
+        camera.takeVideo(null, 4000);
         waitForVideoEnd(true);
     }
 
@@ -460,7 +459,7 @@ public class IntegrationTest extends BaseTest {
     public void testEndVideo_withoutStarting() {
         camera.setSessionType(SessionType.VIDEO);
         waitForOpen(true);
-        camera.stopCapturingVideo();
+        camera.stopVideo();
         waitForVideoEnd(false);
     }
 
@@ -510,7 +509,7 @@ public class IntegrationTest extends BaseTest {
 
     @Test
     public void testCapturePicture_beforeStarted() {
-        camera.capturePicture();
+        camera.takePicture();
         waitForPicture(false);
     }
 
@@ -522,8 +521,8 @@ public class IntegrationTest extends BaseTest {
         CountDownLatch latch = new CountDownLatch(2);
         doCountDown(latch).when(listener).onPictureTaken(any(byte[].class));
 
-        camera.capturePicture();
-        camera.capturePicture();
+        camera.takePicture();
+        camera.takePicture();
         boolean did = latch.await(4, TimeUnit.SECONDS);
         assertFalse(did);
         assertEquals(latch.getCount(), 1);
@@ -535,7 +534,7 @@ public class IntegrationTest extends BaseTest {
         waitForOpen(true);
 
         Size size = camera.getPictureSize();
-        camera.capturePicture();
+        camera.takePicture();
         byte[] jpeg = waitForPicture(true);
         Bitmap b = CameraUtils.decodeBitmap(jpeg, Integer.MAX_VALUE, Integer.MAX_VALUE);
         // Result can actually have swapped dimensions
@@ -546,7 +545,7 @@ public class IntegrationTest extends BaseTest {
 
     @Test
     public void testCaptureSnapshot_beforeStarted() {
-        camera.captureSnapshot();
+        camera.takePictureSnapshot();
         waitForPicture(false);
     }
 
@@ -558,8 +557,8 @@ public class IntegrationTest extends BaseTest {
         CountDownLatch latch = new CountDownLatch(2);
         doCountDown(latch).when(listener).onPictureTaken(any(byte[].class));
 
-        camera.captureSnapshot();
-        camera.captureSnapshot();
+        camera.takePictureSnapshot();
+        camera.takePictureSnapshot();
         boolean did = latch.await(6, TimeUnit.SECONDS);
         assertFalse(did);
         assertEquals(1, latch.getCount());
@@ -571,7 +570,7 @@ public class IntegrationTest extends BaseTest {
         waitForOpen(true);
 
         Size size = camera.getPreviewSize();
-        camera.captureSnapshot();
+        camera.takePictureSnapshot();
         byte[] jpeg = waitForPicture(true);
         Bitmap b = CameraUtils.decodeBitmap(jpeg, Integer.MAX_VALUE, Integer.MAX_VALUE);
         // Result can actually have swapped dimensions
@@ -609,7 +608,7 @@ public class IntegrationTest extends BaseTest {
 
         // In Camera1, snapshots will clear the preview callback
         // Ensure we restore correctly
-        camera.captureSnapshot();
+        camera.takePictureSnapshot();
         waitForPicture(true);
 
         assert30Frames(processor);

cameraview/src/androidTest/java/com/otaliastudios/cameraview/MockCameraController.java

@@ -92,20 +92,20 @@ public class MockCameraController extends CameraController {
     }
 
     @Override
-    void capturePicture() {
+    void takePicture() {
         mPictureCaptured = true;
     }
 
     @Override
-    void captureSnapshot() {
+    void takePictureSnapshot() {
     }
 
     @Override
-    void startVideo(@NonNull File file) {
+    void takeVideo(@NonNull File file) {
     }
 
     @Override
-    void endVideo() {
+    void stopVideo() {
     }
 
     @Override

cameraview/src/main/java/com/otaliastudios/cameraview/Camera1.java

@@ -207,7 +207,7 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
 
         if (mCamera != null) {
             LOG.i("onStop:", "Clean up.", "Ending video.");
-            endVideoImmediately();
+            stopVideoImmediately();
 
             try {
                 LOG.i("onStop:", "Clean up.", "Stopping preview.");
@@ -500,12 +500,12 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
     }
 
     @Override
-    void capturePicture() {
-        LOG.v("capturePicture: scheduling");
+    void takePicture() {
+        LOG.v("takePicture: scheduling");
         schedule(null, true, new Runnable() {
             @Override
             public void run() {
-                LOG.v("capturePicture: performing.", mIsCapturingImage);
+                LOG.v("takePicture: performing.", mIsCapturingImage);
                 if (mIsCapturingImage) return;
                 if (mIsCapturingVideo && !mCameraOptions.isVideoSnapshotSupported()) return;
 
@@ -530,7 +530,7 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
                             @Override
                             public void onPictureTaken(byte[] data, final Camera camera) {
                                 mIsCapturingImage = false;
-                                mCameraCallbacks.processImage(data, outputMatchesView, outputFlip);
+                                mCameraCallbacks.processPicture(data, outputMatchesView, outputFlip);
                                 camera.startPreview(); // This is needed, read somewhere in the docs.
                             }
                         }
@@ -541,17 +541,17 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
 
 
     @Override
-    void captureSnapshot() {
-        LOG.v("captureSnapshot: scheduling");
+    void takePictureSnapshot() {
+        LOG.v("takePictureSnapshot: scheduling");
         schedule(null, true, new Runnable() {
             @Override
             public void run() {
-                LOG.v("captureSnapshot: performing.", mIsCapturingImage);
+                LOG.v("takePictureSnapshot: performing.", mIsCapturingImage);
                 if (mIsCapturingImage) return;
                 // This won't work while capturing a video.
-                // Switch to capturePicture.
+                // Switch to takePicture.
                 if (mIsCapturingVideo) {
-                    capturePicture();
+                    takePicture();
                     return;
                 }
                 mIsCapturingImage = true;
@@ -577,9 +577,9 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
                             @Override
                             public void run() {
 
-                                LOG.v("captureSnapshot: rotating.");
+                                LOG.v("takePictureSnapshot: rotating.");
                                 byte[] rotatedData = RotationHelper.rotate(data, preWidth, preHeight, sensorToOutput);
-                                LOG.v("captureSnapshot: rotated.");
+                                LOG.v("takePictureSnapshot: rotated.");
                                 YuvImage yuv = new YuvImage(rotatedData, format, postWidth, postHeight, null);
                                 mCameraCallbacks.processSnapshot(yuv, outputMatchesView, outputFlip);
                                 mIsCapturingImage = false;
@@ -631,7 +631,7 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
 
 
     @Override
-    void startVideo(@NonNull final File videoFile) {
+    void takeVideo(@NonNull final File videoFile) {
         schedule(mStartVideoTask, true, new Runnable() {
             @Override
             public void run() {
@@ -647,7 +647,7 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
                         LOG.e("Error while starting MediaRecorder. Swallowing.", e);
                         mVideoFile = null;
                         mCamera.lock();
-                        endVideoImmediately();
+                        stopVideoImmediately();
                     }
                 } else {
                     throw new IllegalStateException("Can't record video while session type is picture");
@@ -657,25 +657,25 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
     }
 
     @Override
-    void endVideo() {
+    void stopVideo() {
         schedule(null, false, new Runnable() {
             @Override
             public void run() {
-                endVideoImmediately();
+                stopVideoImmediately();
             }
         });
     }
 
     @WorkerThread
-    private void endVideoImmediately() {
-        LOG.i("endVideoImmediately:", "is capturing:", mIsCapturingVideo);
+    private void stopVideoImmediately() {
+        LOG.i("stopVideoImmediately:", "is capturing:", mIsCapturingVideo);
         mIsCapturingVideo = false;
         if (mMediaRecorder != null) {
             try {
                 mMediaRecorder.stop();
             } catch (Exception e) {
-                // This can happen if endVideo() is called right after startVideo(). We don't care.
-                LOG.w("endVideoImmediately:", "Error while closing media recorder. Swallowing", e);
+                // This can happen if stopVideo() is called right after takeVideo(). We don't care.
+                LOG.w("stopVideoImmediately:", "Error while closing media recorder. Swallowing", e);
             }
             mMediaRecorder.release();
             mMediaRecorder = null;
@@ -736,7 +736,7 @@ class Camera1 extends CameraController implements Camera.PreviewCallback, Camera
                 switch (what) {
                     case MediaRecorder.MEDIA_RECORDER_INFO_MAX_DURATION_REACHED:
                     case MediaRecorder.MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED:
-                        endVideoImmediately();
+                        stopVideoImmediately();
                         break;
                 }
             }

cameraview/src/main/java/com/otaliastudios/cameraview/Camera2.java

@@ -86,22 +86,22 @@ class Camera2 extends CameraController {
     }
 
     @Override
-    void capturePicture() {
+    void takePicture() {
 
     }
 
     @Override
-    void captureSnapshot() {
+    void takePictureSnapshot() {
 
     }
 
     @Override
-    void startVideo(@NonNull File file) {
+    void takeVideo(@NonNull File file) {
 
     }
 
     @Override
-    void endVideo() {
+    void stopVideo() {
 
     }
 

cameraview/src/main/java/com/otaliastudios/cameraview/CameraController.java

@@ -325,13 +325,13 @@ abstract class CameraController implements
     // Throw if capturing. If in video session, recompute capture size, and, if needed, preview size.
     abstract void setVideoQuality(VideoQuality videoQuality);
 
-    abstract void capturePicture();
+    abstract void takePicture();
 
-    abstract void captureSnapshot();
+    abstract void takePictureSnapshot();
 
-    abstract void startVideo(@NonNull File file);
+    abstract void takeVideo(@NonNull File file);
 
-    abstract void endVideo();
+    abstract void stopVideo();
 
     abstract void startAutoFocus(@Nullable Gesture gesture, PointF point);
 

cameraview/src/main/java/com/otaliastudios/cameraview/CameraListener.java

@@ -50,8 +50,8 @@ public abstract class CameraListener {
 
 
     /**
-     * Notifies that a picture previously captured with {@link CameraView#capturePicture()}
-     * or {@link CameraView#captureSnapshot()} is ready to be shown or saved.
+     * Notifies that a picture previously captured with {@link CameraView#takePicture()}
+     * or {@link CameraView#takePictureSnapshot()} is ready to be shown or saved.
      *
      * If planning to get a bitmap, you can use {@link CameraUtils#decodeBitmap(byte[], CameraUtils.BitmapCallback)}
      * to decode the byte array taking care about orientation.
@@ -66,7 +66,7 @@ public abstract class CameraListener {
 
     /**
      * Notifies that a video capture has just ended. The file parameter is the one that
-     * was passed to {@link CameraView#startCapturingVideo(File)}, if any.
+     * was passed to {@link CameraView#takeVideo(File)}, if any.
      * If not, the camera fallsback to:
      * <code>
      *     new File(getContext().getExternalFilesDir(null), "video.mp4");

cameraview/src/main/java/com/otaliastudios/cameraview/CameraView.java

@@ -491,7 +491,7 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
         switch (action) {
 
             case CAPTURE:
-                mCameraController.capturePicture();
+                mCameraController.takePicture();
                 break;
 
             case FOCUS:
@@ -989,8 +989,8 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
     /**
      * Set the current session type to either picture or video.
      * When sessionType is video,
-     * - {@link #startCapturingVideo(File)} will not throw any exception
-     * - {@link #capturePicture()} might fallback to {@link #captureSnapshot()} or might not work
+     * - {@link #takeVideo(File)} will not throw any exception
+     * - {@link #takePicture()} might fallback to {@link #takePictureSnapshot()} or might not work
      *
      * @see SessionType#PICTURE
      * @see SessionType#VIDEO
@@ -1067,20 +1067,6 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
     }
 
 
-    /**
-     * Sets a {@link CameraListener} instance to be notified of all
-     * interesting events that will happen during the camera lifecycle.
-     *
-     * @param cameraListener a listener for events.
-     * @deprecated use {@link #addCameraListener(CameraListener)} instead.
-     */
-    @Deprecated
-    public void setCameraListener(CameraListener cameraListener) {
-        mListeners.clear();
-        addCameraListener(cameraListener);
-    }
-
-
     /**
      * Adds a {@link CameraListener} instance to be notified of all
      * interesting events that happen during the camera lifecycle.
@@ -1155,12 +1141,12 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
      * was registered.
      *
      * Note that if sessionType is {@link SessionType#VIDEO}, this
-     * might fall back to {@link #captureSnapshot()} (that is, we might capture a preview frame).
+     * might fall back to {@link #takePictureSnapshot()} (that is, we might capture a preview frame).
      *
-     * @see #captureSnapshot()
+     * @see #takePictureSnapshot()
      */
-    public void capturePicture() {
-        mCameraController.capturePicture();
+    public void takePicture() {
+        mCameraController.takePicture();
     }
 
 
@@ -1169,25 +1155,13 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
      * This eventually triggers {@link CameraListener#onPictureTaken(byte[])} if a listener
      * was registered.
      *
-     * The difference with {@link #capturePicture()} is that this capture is faster, so it might be
+     * The difference with {@link #takePicture()} is that this capture is faster, so it might be
      * better on slower cameras, though the result can be generally blurry or low quality.
      *
-     * @see #capturePicture()
+     * @see #takePicture()
      */
-    public void captureSnapshot() {
-        mCameraController.captureSnapshot();
-    }
-
-
-    /**
-     * Starts recording a video, in a file called "video.mp4" in the default folder.
-     * This is discouraged, please use {@link #startCapturingVideo(File)} instead.
-     *
-     * @deprecated see {@link #startCapturingVideo(File)}
-     */
-    @Deprecated
-    public void startCapturingVideo() {
-        startCapturingVideo(null);
+    public void takePictureSnapshot() {
+        mCameraController.takePictureSnapshot();
     }
 
 
@@ -1197,11 +1171,11 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
      *
      * @param file a file where the video will be saved
      */
-    public void startCapturingVideo(File file) {
+    public void takeVideo(File file) {
         if (file == null) {
             file = new File(getContext().getFilesDir(), "video.mp4");
         }
-        mCameraController.startVideo(file);
+        mCameraController.takeVideo(file);
         mUiHandler.post(new Runnable() {
             @Override
             public void run() {
@@ -1221,11 +1195,8 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
      * @param file a file where the video will be saved
      * @param durationMillis recording max duration
      *
-     * @deprecated use {@link #setVideoMaxDuration(int)} instead.
      */
-    @Deprecated
-    public void startCapturingVideo(File file, long durationMillis) {
-        // TODO: v2: change signature to int, or remove (better).
+    public void takeVideo(File file, int durationMillis) {
         final int old = getVideoMaxDuration();
         addCameraListener(new CameraListener() {
             @Override
@@ -1234,8 +1205,8 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
                 removeCameraListener(this);
             }
         });
-        setVideoMaxDuration((int) durationMillis);
-        startCapturingVideo(file);
+        setVideoMaxDuration(durationMillis);
+        takeVideo(file);
     }
 
 
@@ -1246,8 +1217,8 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
      * Stops capturing video, if there was a video record going on.
      * This will fire {@link CameraListener#onVideoTaken(File)}.
      */
-    public void stopCapturingVideo() {
-        mCameraController.endVideo();
+    public void stopVideo() {
+        mCameraController.stopVideo();
         mUiHandler.post(new Runnable() {
             @Override
             public void run() {
@@ -1260,6 +1231,8 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
     /**
      * Returns the size used for the preview,
      * or null if it hasn't been computed (for example if the surface is not ready).
+     * This is the size of snapshots.
+     *
      * @return a Size
      */
     @Nullable
@@ -1271,6 +1244,7 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
     /**
      * Returns the size used for the capture,
      * or null if it hasn't been computed yet (for example if the surface is not ready).
+     *
      * @return a Size
      */
     @Nullable
@@ -1279,18 +1253,6 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
     }
 
 
-    /**
-     * Returns the size used for capturing snapshots.
-     * This is equal to {@link #getPreviewSize()}.
-     *
-     * @return a Size
-     */
-    @Nullable
-    public Size getSnapshotSize() {
-        return getPreviewSize();
-    }
-
-
     // If we end up here, we're in M.
     @TargetApi(Build.VERSION_CODES.M)
     private void requestPermissions(boolean requestCamera, boolean requestAudio) {
@@ -1436,7 +1398,7 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
         void dispatchOnCameraClosed();
         void onCameraPreviewSizeChanged();
         void onShutter(boolean shouldPlaySound);
-        void processImage(byte[] jpeg, boolean consistentWithView, boolean flipHorizontally);
+        void processPicture(byte[] jpeg, boolean consistentWithView, boolean flipHorizontally);
         void processSnapshot(YuvImage image, boolean consistentWithView, boolean flipHorizontally);
         void dispatchOnVideoTaken(File file);
         void dispatchOnFocusStart(@Nullable Gesture trigger, PointF where);
@@ -1520,8 +1482,8 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
          *                         because it was taken with the front camera.
          */
         @Override
-        public void processImage(final byte[] jpeg, final boolean consistentWithView, final boolean flipHorizontally) {
-            mLogger.i("processImage");
+        public void processPicture(final byte[] jpeg, final boolean consistentWithView, final boolean flipHorizontally) {
+            mLogger.i("processPicture");
             dispatchOnPictureTaken(jpeg);
             // TODO: remove.
         }
@@ -1697,36 +1659,6 @@ public class CameraView extends FrameLayout implements LifecycleObserver {
 
     //region deprecated APIs
 
-    /**
-     * @deprecated use {@link #getPictureSize()} instead.
-     */
-    @Deprecated
-    @Nullable
-    public Size getCaptureSize() {
-        return getPictureSize();
-    }
-
-    /**
-     * Toggles the flash mode between {@link Flash#OFF},
-     * {@link Flash#ON} and {@link Flash#AUTO}, in this order.
-     *
-     * @deprecated Don't use this. Flash values might not be supported,
-     *             and the return value is unreliable.
-     *
-     * @return the new flash value
-     */
-    @Deprecated
-    public Flash toggleFlash() {
-        Flash flash = mCameraController.getFlash();
-        switch (flash) {
-            case OFF: setFlash(Flash.ON); break;
-            case ON: setFlash(Flash.AUTO); break;
-            case AUTO: case TORCH: setFlash(Flash.OFF); break;
-        }
-        return mCameraController.getFlash();
-    }
-
-
     /* for tests */int getCameraId(){
         return mCameraController.mCameraId;
     }

demo/src/main/java/com/otaliastudios/cameraview/demo/CameraActivity.java

@@ -153,7 +153,7 @@ public class CameraActivity extends AppCompatActivity implements View.OnClickLis
         mCaptureTime = System.currentTimeMillis();
         mCaptureNativeSize = camera.getPictureSize();
         message("Capturing picture...", false);
-        camera.capturePicture();
+        camera.takePicture();
     }
 
     private void captureVideo() {
@@ -164,7 +164,7 @@ public class CameraActivity extends AppCompatActivity implements View.OnClickLis
         if (mCapturingPicture || mCapturingVideo) return;
         mCapturingVideo = true;
         message("Recording for 8 seconds...", true);
-        camera.startCapturingVideo(null, 8000);
+        camera.takeVideo(null, 8000);
     }
 
     private void toggleCamera() {