1 /* 2 * Copyright (C) 2013 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 package android.hardware.camera2; 17 18 /** 19 * A report of failed capture for a single image capture from the image sensor. 20 * 21 * <p>CaptureFailures are produced by a {@link CameraDevice} if processing a 22 * {@link CaptureRequest} fails, either partially or fully. Use {@link #getReason} 23 * to determine the specific nature of the failed capture.</p> 24 * 25 * <p>Receiving a CaptureFailure means that the metadata associated with that frame number 26 * has been dropped -- no {@link CaptureResult} with the same frame number will be 27 * produced.</p> 28 */ 29 public class CaptureFailure { 30 /** 31 * The {@link CaptureResult} has been dropped this frame only due to an error 32 * in the framework. 33 * 34 * @see #getReason() 35 */ 36 public static final int REASON_ERROR = 0; 37 38 /** 39 * The capture has failed due to a {@link CameraCaptureSession#abortCaptures} call from the 40 * application. 41 * 42 * @see #getReason() 43 */ 44 public static final int REASON_FLUSHED = 1; 45 46 private final CaptureRequest mRequest; 47 private final int mReason; 48 private final boolean mDropped; 49 private final int mSequenceId; 50 private final long mFrameNumber; 51 52 /** 53 * @hide 54 */ 55 public CaptureFailure(CaptureRequest request, int reason, boolean dropped, int sequenceId, 56 long frameNumber) { 57 mRequest = request; 58 mReason = reason; 59 mDropped = dropped; 60 mSequenceId = sequenceId; 61 mFrameNumber = frameNumber; 62 } 63 64 /** 65 * Get the request associated with this failed capture. 66 * 67 * <p>Whenever a request is unsuccessfully captured, with 68 * {@link CameraCaptureSession.CaptureCallback#onCaptureFailed}, 69 * the {@code failed capture}'s {@code getRequest()} will return that {@code request}. 70 * </p> 71 * 72 * <p>In particular, 73 * <code><pre>cameraDevice.capture(someRequest, new CaptureCallback() { 74 * {@literal @}Override 75 * void onCaptureFailed(CaptureRequest myRequest, CaptureFailure myFailure) { 76 * assert(myFailure.getRequest.equals(myRequest) == true); 77 * } 78 * }; 79 * </code></pre> 80 * </p> 81 * 82 * @return The request associated with this failed capture. Never {@code null}. 83 */ 84 public CaptureRequest getRequest() { 85 return mRequest; 86 } 87 88 /** 89 * Get the frame number associated with this failed capture. 90 * 91 * <p>Whenever a request has been processed, regardless of failed capture or success, 92 * it gets a unique frame number assigned to its future result/failed capture.</p> 93 * 94 * <p>This value monotonically increments, starting with 0, 95 * for every new result or failure; and the scope is the lifetime of the 96 * {@link CameraDevice}.</p> 97 * 98 * @return long frame number 99 */ 100 public long getFrameNumber() { 101 return mFrameNumber; 102 } 103 104 /** 105 * Determine why the request was dropped, whether due to an error or to a user 106 * action. 107 * 108 * @return int One of {@code REASON_*} integer constants. 109 * 110 * @see #REASON_ERROR 111 * @see #REASON_FLUSHED 112 */ 113 public int getReason() { 114 return mReason; 115 } 116 117 /** 118 * Determine if the image was captured from the camera. 119 * 120 * <p>If the image was not captured, no image buffers will be available. 121 * If the image was captured, then image buffers may be available.</p> 122 * 123 * @return boolean True if the image was captured, false otherwise. 124 */ 125 public boolean wasImageCaptured() { 126 return !mDropped; 127 } 128 129 /** 130 * The sequence ID for this failed capture that was returned by the 131 * {@link CameraCaptureSession#capture} family of functions. 132 * 133 * <p>The sequence ID is a unique monotonically increasing value starting from 0, 134 * incremented every time a new group of requests is submitted to the CameraDevice.</p> 135 * 136 * @return int The ID for the sequence of requests that this capture failure is the result of 137 * 138 * @see CameraDevice.CaptureCallback#onCaptureSequenceCompleted 139 */ 140 public int getSequenceId() { 141 return mSequenceId; 142 } 143 } 144