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 import android.hardware.camera2.impl.PhysicalCaptureResultInfo; 23 24 import java.util.ArrayList; 25 import java.util.Collections; 26 import java.util.HashMap; 27 import java.util.List; 28 import java.util.Map; 29 30 /** 31 * <p>The total assembled results of a single image capture from the image sensor.</p> 32 * 33 * <p>Contains the final configuration for the capture hardware (sensor, lens, 34 * flash), the processing pipeline, the control algorithms, and the output 35 * buffers.</p> 36 * 37 * <p>A {@code TotalCaptureResult} is produced by a {@link CameraDevice} after processing a 38 * {@link CaptureRequest}. All properties listed for capture requests can also 39 * be queried on the capture result, to determine the final values used for 40 * capture. The result also includes additional metadata about the state of the 41 * camera device during the capture.</p> 42 * 43 * <p>All properties returned by {@link CameraCharacteristics#getAvailableCaptureResultKeys()} 44 * are available (that is {@link CaptureResult#get} will return non-{@code null}, if and only if 45 * that key that was enabled by the request. A few keys such as 46 * {@link CaptureResult#STATISTICS_FACES} are disabled by default unless enabled with a switch (such 47 * as {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE}). Refer to each key documentation on 48 * a case-by-case basis.</p> 49 * 50 * <p>For a logical multi-camera device, if the CaptureRequest contains a surface for an underlying 51 * physical camera, the corresponding {@link TotalCaptureResult} object will include the metadata 52 * for that physical camera. And the mapping between the physical camera id and result metadata 53 * can be accessed via {@link #getPhysicalCameraResults}. If all requested surfaces are for the 54 * logical camera, no metadata for physical camera will be included.</p> 55 * 56 * <p>{@link TotalCaptureResult} objects are immutable.</p> 57 * 58 * @see CameraCaptureSession.CaptureCallback#onCaptureCompleted 59 */ 60 public final class TotalCaptureResult extends CaptureResult { 61 62 private final List<CaptureResult> mPartialResults; 63 private final int mSessionId; 64 // The map between physical camera ids and their total capture result 65 private final HashMap<String, TotalCaptureResult> mPhysicalCaptureResults; 66 67 /** 68 * Takes ownership of the passed-in camera metadata and the partial results 69 * 70 * @param partials a list of partial results; {@code null} will be substituted for an empty list 71 * @hide 72 */ TotalCaptureResult(String logicalCameraId, CameraMetadataNative results, CaptureRequest parent, CaptureResultExtras extras, List<CaptureResult> partials, int sessionId, PhysicalCaptureResultInfo[] physicalResults)73 public TotalCaptureResult(String logicalCameraId, CameraMetadataNative results, 74 CaptureRequest parent, CaptureResultExtras extras, List<CaptureResult> partials, 75 int sessionId, PhysicalCaptureResultInfo[] physicalResults) { 76 super(logicalCameraId, results, parent, extras); 77 78 if (partials == null) { 79 mPartialResults = new ArrayList<>(); 80 } else { 81 mPartialResults = partials; 82 } 83 84 mSessionId = sessionId; 85 86 mPhysicalCaptureResults = new HashMap<String, TotalCaptureResult>(); 87 for (PhysicalCaptureResultInfo onePhysicalResult : physicalResults) { 88 TotalCaptureResult physicalResult = new TotalCaptureResult( 89 onePhysicalResult.getCameraId(), 90 onePhysicalResult.getCameraMetadata(), 91 parent, extras, /*partials*/null, sessionId, new PhysicalCaptureResultInfo[0]); 92 mPhysicalCaptureResults.put(onePhysicalResult.getCameraId(), 93 physicalResult); 94 } 95 } 96 97 /** 98 * Takes ownership of the passed-in camera metadata and the partial results 99 * 100 * @param partials a list of partial results; {@code null} will be substituted for an empty list 101 * @hide 102 */ TotalCaptureResult(String logicalCameraId, CameraMetadataNative results, CaptureRequest parent, int requestId, long frameNumber, List<CaptureResult> partials, int sessionId, PhysicalCaptureResultInfo[] physicalResults)103 public TotalCaptureResult(String logicalCameraId, CameraMetadataNative results, 104 CaptureRequest parent, int requestId, long frameNumber, List<CaptureResult> partials, 105 int sessionId, PhysicalCaptureResultInfo[] physicalResults) { 106 super(logicalCameraId, results, parent, requestId, frameNumber); 107 108 if (partials == null) { 109 mPartialResults = new ArrayList<>(); 110 } else { 111 mPartialResults = partials; 112 } 113 114 mSessionId = sessionId; 115 116 mPhysicalCaptureResults = new HashMap<String, TotalCaptureResult>(); 117 for (PhysicalCaptureResultInfo onePhysicalResult : physicalResults) { 118 TotalCaptureResult physicalResult = new TotalCaptureResult( 119 onePhysicalResult.getCameraId(), 120 onePhysicalResult.getCameraMetadata(), 121 parent, requestId, frameNumber, /*partials*/null, sessionId, 122 new PhysicalCaptureResultInfo[0]); 123 mPhysicalCaptureResults.put(onePhysicalResult.getCameraId(), 124 physicalResult); 125 } 126 } 127 128 /** 129 * Creates a request-less result. 130 * 131 * <p><strong>For testing only.</strong></p> 132 * @hide 133 */ TotalCaptureResult(CameraMetadataNative results, int sequenceId)134 public TotalCaptureResult(CameraMetadataNative results, int sequenceId) { 135 super(results, sequenceId); 136 137 mPartialResults = new ArrayList<>(); 138 mSessionId = CameraCaptureSession.SESSION_ID_NONE; 139 mPhysicalCaptureResults = new HashMap<String, TotalCaptureResult>(); 140 } 141 142 /** 143 * Get the read-only list of partial results that compose this total result. 144 * 145 * <p>The list is returned is unmodifiable; attempting to modify it will result in a 146 * {@code UnsupportedOperationException} being thrown.</p> 147 * 148 * <p>The list size will be inclusive between {@code 0} and 149 * {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT}, with elements in ascending order 150 * of when {@link CameraCaptureSession.CaptureCallback#onCaptureProgressed} was invoked.</p> 151 * 152 * @return unmodifiable list of partial results 153 */ 154 @NonNull getPartialResults()155 public List<CaptureResult> getPartialResults() { 156 return Collections.unmodifiableList(mPartialResults); 157 } 158 159 /** 160 * Get the ID of the session where the capture request of this result was submitted. 161 * 162 * @return The session ID 163 * @hide 164 */ getSessionId()165 public int getSessionId() { 166 return mSessionId; 167 } 168 169 /** 170 * Get the map between physical camera ids and their capture result metadata 171 * 172 * <p>This function can be called for logical multi-camera devices, which are devices that have 173 * REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA capability and calls to {@link 174 * CameraCharacteristics#getPhysicalCameraIds} return a non-empty set of physical devices that 175 * are backing the logical camera.</p> 176 * 177 * <p>If one or more streams from the underlying physical cameras were requested by the 178 * corresponding capture request, this function returns the result metadata for those physical 179 * cameras. Otherwise, an empty map is returned.</p> 180 181 * @return unmodifiable map between physical camera ids and their capture result metadata 182 * 183 * @deprecated 184 * <p>Please use {@link #getPhysicalCameraTotalResults()} instead to get the 185 * physical cameras' {@code TotalCaptureResult}.</p> 186 */ getPhysicalCameraResults()187 public Map<String, CaptureResult> getPhysicalCameraResults() { 188 return Collections.unmodifiableMap(mPhysicalCaptureResults); 189 } 190 191 /** 192 * Get the map between physical camera ids and their total capture result metadata 193 * 194 * <p>This function can be called for logical multi-camera devices, which are devices that have 195 * REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA capability.</p> 196 * 197 * <p>If one or more streams from the underlying physical cameras were requested by the 198 * corresponding capture request, this function returns the total result metadata for those 199 * physical cameras. Otherwise, an empty map is returned.</p> 200 * 201 * <p>This function replaces the deprecated {@link #getPhysicalCameraResults}, and its return 202 * value is a map of TotalCaptureResult rather than CaptureResult. </p> 203 * 204 * <p>To reprocess an image from a physical camera stream, typically returned from a 205 * {@link MultiResolutionImageReader}, the application must look up this map to get the {@link 206 * TotalCaptureResult} from the physical camera and pass it to {@link 207 * CameraDevice#createReprocessCaptureRequest}.</p> 208 * 209 * @return unmodifiable map between physical camera ids and their total capture result metadata 210 */ 211 @NonNull getPhysicalCameraTotalResults()212 public Map<String, TotalCaptureResult> getPhysicalCameraTotalResults() { 213 return Collections.unmodifiableMap(mPhysicalCaptureResults); 214 } 215 } 216