16bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin/* 26bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Copyright (C) 2013 The Android Open Source Project 36bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 46bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Licensed under the Apache License, Version 2.0 (the "License"); 56bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * you may not use this file except in compliance with the License. 66bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * You may obtain a copy of the License at 76bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 86bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * http://www.apache.org/licenses/LICENSE-2.0 96bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 106bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Unless required by applicable law or agreed to in writing, software 116bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * distributed under the License is distributed on an "AS IS" BASIS, 126bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 136bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * See the License for the specific language governing permissions and 146bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * limitations under the License. 156bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 166bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkinpackage android.hardware.camera2; 176bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 186bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin/** 196bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * A report of failed capture for a single image capture from the image sensor. 206bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 216bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>CaptureFailures are produced by a {@link CameraDevice} if processing a 226bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * {@link CaptureRequest} fails, either partially or fully. Use {@link #getReason} 236bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * to determine the specific nature of the failed capture.</p> 246bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 256bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>Receiving a CaptureFailure means that the metadata associated with that frame number 266bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * has been dropped -- no {@link CaptureResult} with the same frame number will be 276bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * produced.</p> 286bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 296bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkinpublic class CaptureFailure { 306bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 316bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * The {@link CaptureResult} has been dropped this frame only due to an error 326bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * in the framework. 336bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 346bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @see #getReason() 356bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 366bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public static final int REASON_ERROR = 0; 376bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 386bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 390a160acf297b583e12a9710c929c4ba9a38f7353Eino-Ville Talvala * The capture has failed due to a {@link CameraCaptureSession#abortCaptures} call from the 400a160acf297b583e12a9710c929c4ba9a38f7353Eino-Ville Talvala * application. 416bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 426bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @see #getReason() 436bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 446bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public static final int REASON_FLUSHED = 1; 456bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 466bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin private final CaptureRequest mRequest; 476bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin private final int mReason; 486bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin private final boolean mDropped; 496bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin private final int mSequenceId; 50edecaee1f23b2e9f3698b76d8b7e86b697588f83Eino-Ville Talvala private final long mFrameNumber; 516bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 526bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 536bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @hide 546bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 556bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public CaptureFailure(CaptureRequest request, int reason, boolean dropped, int sequenceId, 56edecaee1f23b2e9f3698b76d8b7e86b697588f83Eino-Ville Talvala long frameNumber) { 576bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin mRequest = request; 586bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin mReason = reason; 596bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin mDropped = dropped; 606bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin mSequenceId = sequenceId; 616bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin mFrameNumber = frameNumber; 626bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin } 636bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 646bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 656bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Get the request associated with this failed capture. 666bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 676bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>Whenever a request is unsuccessfully captured, with 68fd887436bd111e4d2c7307578a51b5070025b7f2Eino-Ville Talvala * {@link CameraCaptureSession.CaptureCallback#onCaptureFailed}, 696bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * the {@code failed capture}'s {@code getRequest()} will return that {@code request}. 706bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * </p> 716bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 726bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>In particular, 73fd887436bd111e4d2c7307578a51b5070025b7f2Eino-Ville Talvala * <code><pre>cameraDevice.capture(someRequest, new CaptureCallback() { 746bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * {@literal @}Override 756bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * void onCaptureFailed(CaptureRequest myRequest, CaptureFailure myFailure) { 766bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * assert(myFailure.getRequest.equals(myRequest) == true); 776bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * } 786bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * }; 796bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * </code></pre> 806bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * </p> 816bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 826bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @return The request associated with this failed capture. Never {@code null}. 836bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 846bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public CaptureRequest getRequest() { 856bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin return mRequest; 866bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin } 876bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 886bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 896bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Get the frame number associated with this failed capture. 906bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 916bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>Whenever a request has been processed, regardless of failed capture or success, 926bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * it gets a unique frame number assigned to its future result/failed capture.</p> 936bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 946bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>This value monotonically increments, starting with 0, 956bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * for every new result or failure; and the scope is the lifetime of the 966bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * {@link CameraDevice}.</p> 976bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 98edecaee1f23b2e9f3698b76d8b7e86b697588f83Eino-Ville Talvala * @return long frame number 996bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 100edecaee1f23b2e9f3698b76d8b7e86b697588f83Eino-Ville Talvala public long getFrameNumber() { 1016bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin return mFrameNumber; 1026bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin } 1036bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 1046bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 1056bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Determine why the request was dropped, whether due to an error or to a user 1066bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * action. 1076bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 1086bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @return int One of {@code REASON_*} integer constants. 1096bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 1106bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @see #REASON_ERROR 1116bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @see #REASON_FLUSHED 1126bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 1136bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public int getReason() { 1146bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin return mReason; 1156bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin } 1166bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 1176bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 1186bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * Determine if the image was captured from the camera. 1196bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 1206bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>If the image was not captured, no image buffers will be available. 1216bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * If the image was captured, then image buffers may be available.</p> 1226bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 1236bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @return boolean True if the image was captured, false otherwise. 1246bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 1256bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public boolean wasImageCaptured() { 1266bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin return !mDropped; 1276bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin } 1286bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin 1296bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin /** 1306bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * The sequence ID for this failed capture that was returned by the 1310a160acf297b583e12a9710c929c4ba9a38f7353Eino-Ville Talvala * {@link CameraCaptureSession#capture} family of functions. 1326bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 1336bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * <p>The sequence ID is a unique monotonically increasing value starting from 0, 1346bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * incremented every time a new group of requests is submitted to the CameraDevice.</p> 1356bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 1366bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * @return int The ID for the sequence of requests that this capture failure is the result of 1376bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin * 138fd887436bd111e4d2c7307578a51b5070025b7f2Eino-Ville Talvala * @see CameraDevice.CaptureCallback#onCaptureSequenceCompleted 1396bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin */ 1406bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin public int getSequenceId() { 1416bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin return mSequenceId; 1426bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin } 1436bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333Igor Murashkin} 144