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 */
16package 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 */
29public 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