CaptureFailure.java revision 6090995951c6e2e4dcf38102f01793f8a94166e1 
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 CameraDevice#flush} call from the application.
40     *
41     * @see #getReason()
42     */
43    public static final int REASON_FLUSHED = 1;
44
45    private final CaptureRequest mRequest;
46    private final int mReason;
47    private final boolean mDropped;
48    private final int mSequenceId;
49    private final int mFrameNumber;
50
51    /**
52     * @hide
53     */
54    public CaptureFailure(CaptureRequest request, int reason, boolean dropped, int sequenceId,
55            int frameNumber) {
56        mRequest = request;
57        mReason = reason;
58        mDropped = dropped;
59        mSequenceId = sequenceId;
60        mFrameNumber = frameNumber;
61    }
62
63    /**
64     * Get the request associated with this failed capture.
65     *
66     * <p>Whenever a request is unsuccessfully captured, with
67     * {@link CameraDevice.CaptureListener#onCaptureFailed},
68     * the {@code failed capture}'s {@code getRequest()} will return that {@code request}.
69     * </p>
70     *
71     * <p>In particular,
72     * <code><pre>cameraDevice.capture(someRequest, new CaptureListener() {
73     *     {@literal @}Override
74     *     void onCaptureFailed(CaptureRequest myRequest, CaptureFailure myFailure) {
75     *         assert(myFailure.getRequest.equals(myRequest) == true);
76     *     }
77     * };
78     * </code></pre>
79     * </p>
80     *
81     * @return The request associated with this failed capture. Never {@code null}.
82     */
83    public CaptureRequest getRequest() {
84        return mRequest;
85    }
86
87    /**
88     * Get the frame number associated with this failed capture.
89     *
90     * <p>Whenever a request has been processed, regardless of failed capture or success,
91     * it gets a unique frame number assigned to its future result/failed capture.</p>
92     *
93     * <p>This value monotonically increments, starting with 0,
94     * for every new result or failure; and the scope is the lifetime of the
95     * {@link CameraDevice}.</p>
96     *
97     * @return int frame number
98     */
99    public int getFrameNumber() {
100        return mFrameNumber;
101    }
102
103    /**
104     * Determine why the request was dropped, whether due to an error or to a user
105     * action.
106     *
107     * @return int One of {@code REASON_*} integer constants.
108     *
109     * @see #REASON_ERROR
110     * @see #REASON_FLUSHED
111     */
112    public int getReason() {
113        return mReason;
114    }
115
116    /**
117     * Determine if the image was captured from the camera.
118     *
119     * <p>If the image was not captured, no image buffers will be available.
120     * If the image was captured, then image buffers may be available.</p>
121     *
122     * @return boolean True if the image was captured, false otherwise.
123     */
124    public boolean wasImageCaptured() {
125        return !mDropped;
126    }
127
128    /**
129     * The sequence ID for this failed capture that was returned by the
130     * {@link CameraDevice#capture} family of functions.
131     *
132     * <p>The sequence ID is a unique monotonically increasing value starting from 0,
133     * incremented every time a new group of requests is submitted to the CameraDevice.</p>
134     *
135     * @return int The ID for the sequence of requests that this capture failure is the result of
136     *
137     * @see CameraDevice.CaptureListener#onCaptureSequenceCompleted
138     */
139    public int getSequenceId() {
140        return mSequenceId;
141    }
142}
143