Home | History | Annotate | Download | only in camera2 
      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