android/hardware/camera2/CaptureFailure.java

/*
 * 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.annotation.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/**
 * A report of failed capture for a single image capture from the image sensor.
 *
 * <p>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.</p>
 *
 * <p>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.</p>
 */
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 CameraCaptureSession#abortCaptures} call from the
     * application.
     *
     * @see #getReason()
     */
    public static final int REASON_FLUSHED = 1;

     /** @hide */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef(prefix = {"REASON_"}, value =
         {REASON_ERROR,
          REASON_FLUSHED })
     public @interface FailureReason {};

    private final CaptureRequest mRequest;
    private final int mReason;
    private final boolean mDropped;
    private final int mSequenceId;
    private final long mFrameNumber;
    private final String mErrorPhysicalCameraId;

    /**
     * @hide
     */
    public CaptureFailure(CaptureRequest request, int reason,
            boolean dropped, int sequenceId, long frameNumber, String errorPhysicalCameraId) {
        mRequest = request;
        mReason = reason;
        mDropped = dropped;
        mSequenceId = sequenceId;
        mFrameNumber = frameNumber;
        mErrorPhysicalCameraId = errorPhysicalCameraId;
    }

    /**
     * Get the request associated with this failed capture.
     *
     * <p>Whenever a request is unsuccessfully captured, with
     * {@link CameraCaptureSession.CaptureCallback#onCaptureFailed},
     * the {@code failed capture}'s {@code getRequest()} will return that {@code request}.
     * </p>
     *
     * <p>In particular,
     * <code><pre>cameraDevice.capture(someRequest, new CaptureCallback() {
     *     {@literal @}Override
     *     void onCaptureFailed(CaptureRequest myRequest, CaptureFailure myFailure) {
     *         assert(myFailure.getRequest.equals(myRequest) == true);
     *     }
     * };
     * </code></pre>
     * </p>
     *
     * @return The request associated with this failed capture. Never {@code null}.
     */
    @NonNull
    public CaptureRequest getRequest() {
        return mRequest;
    }

    /**
     * Get the frame number associated with this failed capture.
     *
     * <p>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.</p>
     *
     * <p>This value monotonically increments, starting with 0,
     * for every new result or failure; and the scope is the lifetime of the
     * {@link CameraDevice}.</p>
     *
     * @return long frame number
     */
    public long getFrameNumber() {
        return mFrameNumber;
    }

    /**
     * Determine why the request was dropped, whether due to an error or to a user
     * action.
     *
     * @return int The reason code.
     *
     * @see #REASON_ERROR
     * @see #REASON_FLUSHED
     */
    @FailureReason
    public int getReason() {
        return mReason;
    }

    /**
     * Determine if the image was captured from the camera.
     *
     * <p>If the image was not captured, no image buffers will be available.
     * If the image was captured, then image buffers may be available.</p>
     *
     * @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 CameraCaptureSession#capture} family of functions.
     *
     * <p>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.</p>
     *
     * @return int The ID for the sequence of requests that this capture failure is the result of
     *
     * @see CameraCaptureSession.CaptureCallback#onCaptureSequenceCompleted
     */
    public int getSequenceId() {
        return mSequenceId;
    }

    /**
     * The physical camera device ID in case the capture failure comes from a {@link CaptureRequest}
     * with configured physical camera streams for a logical camera.
     *
     * @return String The physical camera device ID of the respective failing output.
     *         {@code null} in case the capture request has no associated physical camera device.
     * @see CaptureRequest.Builder#setPhysicalCameraKey
     * @see android.hardware.camera2.params.OutputConfiguration#setPhysicalCameraId
     */
    public @Nullable String getPhysicalCameraId() {
        return mErrorPhysicalCameraId;
    }
}