1 /*
2  * Copyright (C) 2014 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 
17 package android.hardware.camera2;
18 
19 import android.annotation.NonNull;
20 import android.hardware.camera2.impl.CameraMetadataNative;
21 import android.hardware.camera2.impl.CaptureResultExtras;
22 
23 import java.util.ArrayList;
24 import java.util.Collections;
25 import java.util.List;
26 
27 /**
28  * <p>The total assembled results of a single image capture from the image sensor.</p>
29  *
30  * <p>Contains the final configuration for the capture hardware (sensor, lens,
31  * flash), the processing pipeline, the control algorithms, and the output
32  * buffers.</p>
33  *
34  * <p>A {@code TotalCaptureResult} is produced by a {@link CameraDevice} after processing a
35  * {@link CaptureRequest}. All properties listed for capture requests can also
36  * be queried on the capture result, to determine the final values used for
37  * capture. The result also includes additional metadata about the state of the
38  * camera device during the capture.</p>
39  *
40  * <p>All properties returned by {@link CameraCharacteristics#getAvailableCaptureResultKeys()}
41  * are available (that is {@link CaptureResult#get} will return non-{@code null}, if and only if
42  * that key that was enabled by the request. A few keys such as
43  * {@link CaptureResult#STATISTICS_FACES} are disabled by default unless enabled with a switch (such
44  * as {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE}). Refer to each key documentation on
45  * a case-by-case basis.</p>
46  *
47  * <p>{@link TotalCaptureResult} objects are immutable.</p>
48  *
49  * @see CameraDevice.CaptureCallback#onCaptureCompleted
50  */
51 public final class TotalCaptureResult extends CaptureResult {
52 
53     private final List<CaptureResult> mPartialResults;
54     private final int mSessionId;
55 
56     /**
57      * Takes ownership of the passed-in camera metadata and the partial results
58      *
59      * @param partials a list of partial results; {@code null} will be substituted for an empty list
60      * @hide
61      */
TotalCaptureResult(CameraMetadataNative results, CaptureRequest parent, CaptureResultExtras extras, List<CaptureResult> partials, int sessionId)62     public TotalCaptureResult(CameraMetadataNative results, CaptureRequest parent,
63             CaptureResultExtras extras, List<CaptureResult> partials, int sessionId) {
64         super(results, parent, extras);
65 
66         if (partials == null) {
67             mPartialResults = new ArrayList<>();
68         } else {
69             mPartialResults = partials;
70         }
71 
72         mSessionId = sessionId;
73     }
74 
75     /**
76      * Creates a request-less result.
77      *
78      * <p><strong>For testing only.</strong></p>
79      * @hide
80      */
TotalCaptureResult(CameraMetadataNative results, int sequenceId)81     public TotalCaptureResult(CameraMetadataNative results, int sequenceId) {
82         super(results, sequenceId);
83 
84         mPartialResults = new ArrayList<>();
85         mSessionId = CameraCaptureSession.SESSION_ID_NONE;
86     }
87 
88     /**
89      * Get the read-only list of partial results that compose this total result.
90      *
91      * <p>The list is returned is unmodifiable; attempting to modify it will result in a
92      * {@code UnsupportedOperationException} being thrown.</p>
93      *
94      * <p>The list size will be inclusive between {@code 0} and
95      * {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT}, with elements in ascending order
96      * of when {@link CameraCaptureSession.CaptureCallback#onCaptureProgressed} was invoked.</p>
97      *
98      * @return unmodifiable list of partial results
99      */
100     @NonNull
getPartialResults()101     public List<CaptureResult> getPartialResults() {
102         return Collections.unmodifiableList(mPartialResults);
103     }
104 
105     /**
106      * Get the ID of the session where the capture request of this result was submitted.
107      *
108      * @return The session ID
109      * @hide
110      */
getSessionId()111     public int getSessionId() {
112         return mSessionId;
113     }
114 }
115