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