src/com/android/camera/one/OneCamera.java

   1 /*
   2  * Copyright (C) 2014 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.android.camera.one;
  18
  19 import android.content.Context;
  20 import android.graphics.Bitmap;
  21 import android.location.Location;
  22 import android.net.Uri;
  23 import android.view.Surface;
  24
  25 import com.android.camera.session.CaptureSession;
  26 import com.android.camera.util.Size;
  27
  28 import java.io.File;
  29
  30 /**
  31  * OneCamera is a camera API tailored around our Google Camera application
  32  * needs. It's not a general purpose API but instead offers an API with exactly
  33  * what's needed from the app's side.
  34  */
  35 public interface OneCamera {
  36
  37     /** Which way the camera is facing. */
  38     public static enum Facing {
  39         FRONT, BACK;
  40     }
  41
  42     /**
  43      * Auto focus system status; 1:1 mapping from camera2 AF_STATE.
  44      * <ul>
  45      * <li>{@link #INACTIVE}</li>
  46      * <li>{@link #ACTIVE_SCAN}</li>
  47      * <li>{@link #ACTIVE_FOCUSED}</li>
  48      * <li>{@link #ACTIVE_UNFOCUSED}</li>
  49      * <li>{@link #PASSIVE_SCAN}</li>
  50      * <li>{@link #PASSIVE_FOCUSED}</li>
  51      * <li>{@link #PASSIVE_UNFOCUSED}</li>
  52      * </ul>
  53      */
  54     public static enum AutoFocusState {
  55         /** Indicates AF system is inactive for some reason (could be an error). */
  56         INACTIVE,
  57         /** Indicates active scan in progress. */
  58         ACTIVE_SCAN,
  59         /** Indicates active scan success (in focus). */
  60         ACTIVE_FOCUSED,
  61         /** Indicates active scan failure (not in focus). */
  62         ACTIVE_UNFOCUSED,
  63         /** Indicates passive scan in progress. */
  64         PASSIVE_SCAN,
  65         /** Indicates passive scan success (in focus). */
  66         PASSIVE_FOCUSED,
  67         /** Indicates passive scan failure (not in focus). */
  68         PASSIVE_UNFOCUSED
  69     }
  70
  71     /**
  72      * Auto focus system mode.
  73      * <ul>
  74      * <li>{@link #CONTINUOUS_PICTURE}</li>
  75      * <li>{@link #AUTO}</li>
  76      * </ul>
  77      */
  78     public static enum AutoFocusMode {
  79         /** System is continuously focusing. */
  80         CONTINUOUS_PICTURE,
  81         /** System is running a triggered scan. */
  82         AUTO
  83     }
  84
  85     /**
  86      * Classes implementing this interface will be called when the camera was
  87      * opened or failed to open.
  88      */
  89     public static interface OpenCallback {
  90         /**
  91          * Called when the camera was opened successfully.
  92          *
  93          * @param camera the camera instance that was successfully opened
  94          */
  95         public void onCameraOpened(OneCamera camera);
  96
  97         /**
  98          * Called if opening the camera failed.
  99          */
 100         public void onFailure();
 101     }
 102
 103     /**
 104      * Classes implementing this interface will be called when the camera was
 105      * closed.
 106      */
 107     public static interface CloseCallback {
 108         /** Called when the camera was fully closed. */
 109         public void onCameraClosed();
 110     }
 111
 112     /**
 113      * Classes implementing this interface can be informed when we're ready to
 114      * take a picture of if setting up the capture pipeline failed.
 115      */
 116     public static interface CaptureReadyCallback {
 117         /** After this is called, the system is ready for capture requests. */
 118         public void onReadyForCapture();
 119
 120         /**
 121          * Indicates that something went wrong during setup and the system is
 122          * not ready for capture requests.
 123          */
 124         public void onSetupFailed();
 125     }
 126
 127     /**
 128      * Classes implementing this interface can be informed when the state of
 129      * capture changes.
 130      */
 131     public static interface ReadyStateChangedListener {
 132         /**
 133          * Called when the camera is either ready or not ready to take a picture
 134          * right now.
 135          */
 136         public void onReadyStateChanged(boolean readyForCapture);
 137     }
 138
 139     /**
 140      * A class implementing this interface can be passed into the call to take a
 141      * picture in order to receive the resulting image or updated about the
 142      * progress.
 143      */
 144     public static interface PictureCallback {
 145         /**
 146          * Called near the the when an image is being exposed for cameras which
 147          * are exposing a single frame, so that a UI can be presented for the
 148          * capture.
 149          */
 150         public void onQuickExpose();
 151
 152         /**
 153          * Called when a thumbnail image is provided before the final image is
 154          * finished.
 155          */
 156         public void onThumbnailResult(Bitmap bitmap);
 157
 158         /**
 159          * Called when the final picture is done taking
 160          *
 161          * @param session the capture session
 162          */
 163         public void onPictureTaken(CaptureSession session);
 164
 165         /**
 166          * Called when the picture has been saved to disk.
 167          *
 168          * @param uri the URI of the stored data.
 169          */
 170         public void onPictureSaved(Uri uri);
 171
 172         /**
 173          * Called when picture taking failed.
 174          */
 175         public void onPictureTakenFailed();
 176
 177         /**
 178          * Called when capture session is reporting a processing update. This
 179          * should only be called by capture sessions that require the user to
 180          * hold still for a while.
 181          *
 182          * @param progress a value from 0...1, indicating the current processing
 183          *            progress.
 184          */
 185         public void onTakePictureProgress(float progress);
 186     }
 187
 188     /**
 189      * Classes implementing this interface will be called whenever the camera
 190      * encountered an error.
 191      */
 192     public static interface CameraErrorListener {
 193         /** Called when the camera encountered an error. */
 194         public void onCameraError();
 195     }
 196
 197     /**
 198      * Classes implementing this interface will be called when the state of the
 199      * focus changes. Guaranteed not to stay stuck in scanning state past some
 200      * reasonable timeout even if Camera API is stuck.
 201      */
 202     public static interface FocusStateListener {
 203         /**
 204          * Called when state of auto focus system changes.
 205          *
 206          * @param state Current auto focus state.
 207          * @param frameNumber Frame number if available.
 208          */
 209         public void onFocusStatusUpdate(AutoFocusState state, long frameNumber);
 210     }
 211
 212     /**
 213      * Parameters to be given to photo capture requests.
 214      */
 215     public static final class PhotoCaptureParameters {
 216         /**
 217          * Flash modes.
 218          * <p>
 219          * Has to be in sync with R.arrays.pref_camera_flashmode_entryvalues.
 220          */
 221         public static enum Flash {
 222             AUTO, OFF, ON
 223         }
 224
 225         /** The title/filename (without suffix) for this capture. */
 226         public String title = null;
 227         /** Called when the capture is completed or failed. */
 228         public PictureCallback callback = null;
 229         /** The device orientation so we can compute the right JPEG rotation. */
 230         public int orientation = Integer.MIN_VALUE;
 231         /** The heading of the device at time of capture. In degrees. */
 232         public int heading = Integer.MIN_VALUE;
 233         /** Flash mode for this capture. */
 234         public Flash flashMode = Flash.AUTO;
 235         /** The location of this capture. */
 236         public Location location = null;
 237
 238         /** Set this to provide a debug folder for this capture. */
 239         public File debugDataFolder;
 240
 241         /**
 242          * Checks whether all required values are set. If one is missing, it
 243          * throws a {@link RuntimeException}.
 244          */
 245         public void checkSanity() {
 246             checkRequired(title);
 247             checkRequired(callback);
 248             checkRequired(orientation);
 249             checkRequired(heading);
 250         }
 251
 252         private void checkRequired(int num) {
 253             if (num == Integer.MIN_VALUE) {
 254                 throw new RuntimeException("Photo capture parameter missing.");
 255             }
 256         }
 257
 258         private void checkRequired(Object obj) {
 259             if (obj == null) {
 260                 throw new RuntimeException("Photo capture parameter missing.");
 261             }
 262         }
 263     }
 264
 265     /**
 266      * Meters and triggers auto focus scan with ROI around tap point.
 267      * <p/>
 268      * Normalized coordinates are referenced to portrait preview window with 0,0
 269      * top left and 1,1 bottom right. Rotation has no effect.
 270      *
 271      * @param nx normalized x coordinate.
 272      * @param nx normalized y coordinate.
 273      */
 274     public void triggerFocusAndMeterAtPoint(float nx, float ny);
 275
 276     /**
 277      * Call this to take a picture.
 278      *
 279      * @param params parameters for taking pictures.
 280      * @param session the capture session for this picture.
 281      */
 282     public void takePicture(PhotoCaptureParameters params, CaptureSession session);
 283
 284     /**
 285      * Sets or replaces a listener that is called whenever the camera encounters
 286      * an error.
 287      */
 288     public void setCameraErrorListener(CameraErrorListener listener);
 289
 290     /**
 291      * Sets or replaces a listener that is called whenever the focus state of
 292      * the camera changes.
 293      */
 294     public void setFocusStateListener(FocusStateListener listener);
 295
 296     /**
 297      * Sets or replaces a listener that is called whenever the state of the
 298      * camera changes to be either ready or not ready to take another picture.
 299      */
 300     public void setReadyStateChangedListener(ReadyStateChangedListener listener);
 301
 302     /**
 303      * Starts a preview stream and renders it to the given surface.
 304      */
 305     public void startPreview(Surface surface, CaptureReadyCallback listener);
 306
 307     /**
 308      * Sets the size of the viewfinder.
 309      * <p>
 310      * The preview size requested from the camera device will depend on this as
 311      * well as the requested photo/video aspect ratio.
 312      */
 313     public void setViewfinderSize(int width, int height);
 314
 315     /**
 316      * @return Whether this camera supports flash.
 317      * @param if true, returns whether flash is supported in enhanced mode. If
 318      *        false, whether flash is supported in normal capture mode.
 319      */
 320     public boolean isFlashSupported(boolean enhanced);
 321
 322     /**
 323      * @return Whether this camera supports enhanced mode, such as HDR.
 324      */
 325     public boolean isSupportingEnhancedMode();
 326
 327     /**
 328      * Closes the camera.
 329      *
 330      * @param closeCallback Optional. Called as soon as the camera is fully
 331      *            closed.
 332      */
 333     public void close(CloseCallback closeCallback);
 334
 335     /**
 336      * @return A list of all supported resolutions.
 337      */
 338     public Size[] getSupportedSizes();
 339
 340     /**
 341      * @return The aspect ratio of the full size capture (usually the native
 342      *         resolution of the camera).
 343      */
 344     public float getFullSizeAspectRatio();
 345
 346     /**
 347      * @return Whether this camera is facing to the back.
 348      */
 349     public boolean isBackFacing();
 350
 351     /**
 352      * @return Whether this camera is facing to the front.
 353      */
 354     public boolean isFrontFacing();
 355
 356     /**
 357      * Get the maximum zoom value.
 358      *
 359      * @return A float number to represent the maximum zoom value(>= 1.0).
 360      */
 361     public float getMaxZoom();
 362
 363     /**
 364      * This function sets the current zoom ratio value.
 365      * <p>
 366      * The zoom range must be [1.0, maxZoom]. The maxZoom can be queried by
 367      * {@link #getMaxZoom}.
 368      *
 369      * @param zoom Zoom ratio value passed to scaler.
 370      */
 371     public void setZoom(float zoom);
 372
 373     /**
 374      * Based on the selected picture size, this returns the best preview size.
 375      *
 376      * @param pictureSize the picture size as selected by the user. A camera
 377      *            might choose not to obey these and therefore the returned
 378      *            preview size might not match the aspect ratio of the given
 379      *            size.
 380      * @param context the android application context
 381      * @return The preview size that best matches the picture aspect ratio that
 382      *         will be taken.
 383      */
 384     public Size pickPreviewSize(Size pictureSize, Context context);
 385 }