/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware.camera2; import android.hardware.camera2.CameraDevice.CaptureListener; /** * A report of failed capture for a single image capture from the image sensor. * *

CaptureFailures are produced by a {@link CameraDevice} if processing a * {@link CaptureRequest} fails, either partially or fully. Use {@link #getReason} * to determine the specific nature of the failed capture.

* *

Receiving a CaptureFailure means that the metadata associated with that frame number * has been dropped -- no {@link CaptureResult} with the same frame number will be * produced.

*/ public class CaptureFailure { /** * The {@link CaptureResult} has been dropped this frame only due to an error * in the framework. * * @see #getReason() */ public static final int REASON_ERROR = 0; /** * The capture has failed due to a {@link CameraDevice#flush} call from the application. * * @see #getReason() */ public static final int REASON_FLUSHED = 1; private final CaptureRequest mRequest; private final int mReason; private final boolean mDropped; private final int mSequenceId; private final int mFrameNumber; /** * @hide */ public CaptureFailure(CaptureRequest request, int reason, boolean dropped, int sequenceId, int frameNumber) { mRequest = request; mReason = reason; mDropped = dropped; mSequenceId = sequenceId; mFrameNumber = frameNumber; } /** * Get the request associated with this failed capture. * *

Whenever a request is unsuccessfully captured, with * {@link CameraDevice.CaptureListener#onCaptureFailed}, * the {@code failed capture}'s {@code getRequest()} will return that {@code request}. *

* *

In particular, *

cameraDevice.capture(someRequest, new CaptureListener() {
     *     {@literal @}Override
     *     void onCaptureFailed(CaptureRequest myRequest, CaptureFailure myFailure) {
     *         assert(myFailure.getRequest.equals(myRequest) == true);
     *     }
     * };
     * 
*

* * @return The request associated with this failed capture. Never {@code null}. */ public CaptureRequest getRequest() { return mRequest; } /** * Get the frame number associated with this failed capture. * *

Whenever a request has been processed, regardless of failed capture or success, * it gets a unique frame number assigned to its future result/failed capture.

* *

This value monotonically increments, starting with 0, * for every new result or failure; and the scope is the lifetime of the * {@link CameraDevice}.

* * @return int frame number */ public int getFrameNumber() { return mFrameNumber; } /** * Determine why the request was dropped, whether due to an error or to a user * action. * * @return int One of {@code REASON_*} integer constants. * * @see #REASON_ERROR * @see #REASON_FLUSHED */ public int getReason() { return mReason; } /** * Determine if the image was captured from the camera. * *

If the image was not captured, no image buffers will be available. * If the image was captured, then image buffers may be available.

* * @return boolean True if the image was captured, false otherwise. */ public boolean wasImageCaptured() { return !mDropped; } /** * The sequence ID for this failed capture that was returned by the * {@link CameraDevice#capture} family of functions. * *

The sequence ID is a unique monotonically increasing value starting from 0, * incremented every time a new group of requests is submitted to the CameraDevice.

* * @return int The ID for the sequence of requests that this capture failure is the result of * * @see CameraDevice.CaptureListener#onCaptureSequenceCompleted */ public int getSequenceId() { return mSequenceId; } }