camera/one/OneCamera.java

/*
 * Copyright (C) 2014 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.camera.one;

import android.content.Context;
import android.location.Location;
import android.net.Uri;
import android.view.Surface;

import com.android.camera.session.CaptureSession;
import com.android.camera.settings.SettingsManager;
import com.android.camera.ui.motion.LinearScale;
import com.android.camera.util.Size;

import java.io.File;

import javax.annotation.Nonnull;

/**
 * OneCamera is a camera API tailored around our Google Camera application
 * needs. It's not a general purpose API but instead offers an API with exactly
 * what's needed from the app's side.
 */
public interface OneCamera {

    /** Which way the camera is facing. */
    public static enum Facing {
        FRONT, BACK;
    }

    /**
     * Auto focus system status; 1:1 mapping from camera2 AF_STATE.
     * <ul>
     * <li>{@link #INACTIVE}</li>
     * <li>{@link #ACTIVE_SCAN}</li>
     * <li>{@link #ACTIVE_FOCUSED}</li>
     * <li>{@link #ACTIVE_UNFOCUSED}</li>
     * <li>{@link #PASSIVE_SCAN}</li>
     * <li>{@link #PASSIVE_FOCUSED}</li>
     * <li>{@link #PASSIVE_UNFOCUSED}</li>
     * </ul>
     */
    public static enum AutoFocusState {
        /** Indicates AF system is inactive for some reason (could be an error). */
        INACTIVE,
        /** Indicates active scan in progress. */
        ACTIVE_SCAN,
        /** Indicates active scan success (in focus). */
        ACTIVE_FOCUSED,
        /** Indicates active scan failure (not in focus). */
        ACTIVE_UNFOCUSED,
        /** Indicates passive scan in progress. */
        PASSIVE_SCAN,
        /** Indicates passive scan success (in focus). */
        PASSIVE_FOCUSED,
        /** Indicates passive scan failure (not in focus). */
        PASSIVE_UNFOCUSED
    }

    /**
     * Classes implementing this interface will be called when the camera was
     * opened or failed to open.
     */
    public static interface OpenCallback {
        /**
         * Called when the camera was opened successfully.
         *
         * @param camera the camera instance that was successfully opened
         */
        public void onCameraOpened(@Nonnull OneCamera camera);

        /**
         * Called if opening the camera failed.
         */
        public void onFailure();

        /**
         * Called if the camera is closed or disconnected while attempting to
         * open.
         */
        public void onCameraClosed();
    }

    /**
     * Classes implementing this interface can be informed when we're ready to
     * take a picture of if setting up the capture pipeline failed.
     */
    public static interface CaptureReadyCallback {
        /** After this is called, the system is ready for capture requests. */
        public void onReadyForCapture();

        /**
         * Indicates that something went wrong during setup and the system is
         * not ready for capture requests.
         */
        public void onSetupFailed();
    }

    /**
     * Classes implementing this interface can be informed when the state of
     * capture changes.
     */
    public static interface ReadyStateChangedListener {
        /**
         * Called when the camera is either ready or not ready to take a picture
         * right now.
         */
        public void onReadyStateChanged(boolean readyForCapture);
    }

    /**
     * A class implementing this interface can be passed into the call to take a
     * picture in order to receive the resulting image or updated about the
     * progress.
     */
    public static interface PictureCallback {
        /**
         * Called near the the when an image is being exposed for cameras which
         * are exposing a single frame, so that a UI can be presented for the
         * capture.
         */
        public void onQuickExpose();

        /**
         * Called when a thumbnail image is provided before the final image is
         * finished.
         */
        public void onThumbnailResult(byte[] jpegData);

        /**
         * Called when the final picture is done taking
         *
         * @param session the capture session
         */
        public void onPictureTaken(CaptureSession session);

        /**
         * Called when the picture has been saved to disk.
         *
         * @param uri the URI of the stored data.
         */
        public void onPictureSaved(Uri uri);

        /**
         * Called when picture taking failed.
         */
        public void onPictureTakingFailed();

        /**
         * Called when capture session is reporting a processing update. This
         * should only be called by capture sessions that require the user to
         * hold still for a while.
         *
         * @param progress a value from 0...1, indicating the current processing
         *            progress.
         */
        public void onTakePictureProgress(float progress);
    }

    /**
     * A class implementing this interface can be passed to a picture saver in
     * order to receive image processing events.
     */
    public static interface PictureSaverCallback {
        /**
         * Called when compressed data for Thumbnail on a remote device (such as
         * Android wear) is available.
         */
        public void onRemoteThumbnailAvailable(byte[] jpegImage);
    }

    /**
     * Classes implementing this interface will be called when the state of the
     * focus changes. Guaranteed not to stay stuck in scanning state past some
     * reasonable timeout even if Camera API is stuck.
     */
    public static interface FocusStateListener {
        /**
         * Called when state of auto focus system changes.
         *
         * @param state Current auto focus state.
         * @param frameNumber Frame number if available.
         */
        public void onFocusStatusUpdate(AutoFocusState state, long frameNumber);
    }

    /**
     * Classes implementing this interface will be called when the focus
     * distance of the physical lens changes.
     */
    public static interface FocusDistanceListener {
        /**
         * Called when physical lens distance on the camera changes.
         */
        public void onFocusDistance(float distance, LinearScale lensRange);
    }

    /**
     * Single instance of the current camera AF state.
     */
    public static class FocusState {
        public final float lensDistance;
        public final boolean isActive;

        /**
         * @param lensDistance The current focal distance.
         * @param isActive Whether the lens is moving, e.g. because of either an
         *            "active scan" or a "passive scan".
         */
        public FocusState(float lensDistance, boolean isActive) {
            this.lensDistance = lensDistance;
            this.isActive = isActive;
        }

        @Override
        public boolean equals(Object o) {
            if (this == o)
                return true;
            if (o == null || getClass() != o.getClass())
                return false;

            FocusState that = (FocusState) o;

            if (Float.compare(that.lensDistance, lensDistance) != 0)
                return false;
            if (isActive != that.isActive)
                return false;

            return true;
        }

        @Override
        public int hashCode() {
            int result = (lensDistance != +0.0f ? Float.floatToIntBits(lensDistance) : 0);
            result = 31 * result + (isActive ? 1 : 0);
            return result;
        }

        @Override
        public String toString() {
            return "FocusState{" +
                  "lensDistance=" + lensDistance +
                  ", isActive=" + isActive +
                  '}';
        }
    }

    /**
     * Parameters to be given to capture requests.
     */
    public static abstract class CaptureParameters {
        /** The title/filename (without suffix) for this capture. */
        public final String title;

        /** The device orientation so we can compute the right JPEG rotation. */
        public final int orientation;

        /** The location of this capture. */
        public final Location location;

        /** Set this to provide a debug folder for this capture. */
        public final File debugDataFolder;

        public CaptureParameters(String title, int orientation, Location location, File
                debugDataFolder) {
            this.title = title;
            this.orientation = orientation;
            this.location = location;
            this.debugDataFolder = debugDataFolder;
        }
    }

    /**
     * Parameters to be given to photo capture requests.
     */
    public static class PhotoCaptureParameters extends CaptureParameters {
        /**
         * Flash modes.
         * <p>
         */
        public static enum Flash {
            AUTO("auto"), OFF("off"), ON("on");

            /**
             * The machine-readable (via {@link #encodeSettingsString} and
             * {@link #decodeSettingsString} string used to represent this flash
             * mode in {@link SettingsManager}.
             * <p>
             * This must be in sync with R.arrays.pref_camera_flashmode_entryvalues.
             */
            private final String mSettingsString;

            Flash(@Nonnull String settingsString) {
                mSettingsString = settingsString;
            }

            @Nonnull
            public String encodeSettingsString() {
                return mSettingsString;
            }

            @Nonnull
            public static Flash decodeSettingsString(@Nonnull String setting) {
                if (AUTO.encodeSettingsString().equals(setting)) {
                    return AUTO;
                } else if (OFF.encodeSettingsString().equals(setting)) {
                    return OFF;
                } else if (ON.encodeSettingsString().equals(setting)) {
                    return ON;
                }
                throw new IllegalArgumentException("Not a valid setting");
            }
        }

        /** Called when the capture is completed or failed. */
        public final PictureCallback callback;
        public final PictureSaverCallback saverCallback;
        /** The heading of the device at time of capture. In degrees. */
        public final int heading;
        /** Zoom value. */
        public final float zoom;
        /** Timer duration in seconds or 0 for no timer. */
        public final float timerSeconds;

        public PhotoCaptureParameters(String title, int orientation, Location location, File
                debugDataFolder, PictureCallback callback, PictureSaverCallback saverCallback,
                int heading, float zoom, float timerSeconds) {
            super(title, orientation, location, debugDataFolder);
            this.callback = callback;
            this.saverCallback = saverCallback;
            this.heading = heading;
            this.zoom = zoom;
            this.timerSeconds = timerSeconds;
        }
    }


    /**
     * Meters and triggers auto focus scan with ROI around tap point.
     * <p/>
     * Normalized coordinates are referenced to portrait preview window with (0,
     * 0) top left and (1, 1) bottom right. Rotation has no effect.
     *
     * @param nx normalized x coordinate.
     * @param ny normalized y coordinate.
     */
    public void triggerFocusAndMeterAtPoint(float nx, float ny);

    /**
     * Call this to take a picture.
     *
     * @param params parameters for taking pictures.
     * @param session the capture session for this picture.
     */
    public void takePicture(PhotoCaptureParameters params, CaptureSession session);

    /**
     * Sets or replaces a listener that is called whenever the focus state of
     * the camera changes.
     */
    public void setFocusStateListener(FocusStateListener listener);

    /**
     * Sets or replaces a listener that is called whenever the focus state of
     * the camera changes.
     */
    public void setFocusDistanceListener(FocusDistanceListener listener);

    /**
     * Sets or replaces a listener that is called whenever the state of the
     * camera changes to be either ready or not ready to take another picture.
     */
    public void setReadyStateChangedListener(ReadyStateChangedListener listener);

    /**
     * Starts a preview stream and renders it to the given surface.
     *
     * @param surface the surface on which to render preview frames
     * @param listener
     */
    public void startPreview(Surface surface, CaptureReadyCallback listener);

    /**
     * Closes the camera.
     */
    public void close();

    /**
     * @return The direction of the camera.
     */
    public Facing getDirection();

    /**
     * Get the maximum zoom value.
     *
     * @return A float number to represent the maximum zoom value(>= 1.0).
     */
    public float getMaxZoom();

    /**
     * This function sets the current zoom ratio value.
     * <p>
     * The zoom range must be [1.0, maxZoom]. The maxZoom can be queried by
     * {@link #getMaxZoom}.
     *
     * @param zoom Zoom ratio value passed to scaler.
     */
    public void setZoom(float zoom);

    /**
     * Based on the selected picture size, this returns the best preview size.
     *
     * @param pictureSize the picture size as selected by the user. A camera
     *            might choose not to obey these and therefore the returned
     *            preview size might not match the aspect ratio of the given
     *            size.
     * @param context the android application context
     * @return The preview size that best matches the picture aspect ratio that
     *         will be taken.
     */
    public Size pickPreviewSize(Size pictureSize, Context context);
}