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