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 id and capture result 65 private final HashMap<String, CaptureResult> 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(CameraMetadataNative results, CaptureRequest parent, CaptureResultExtras extras, List<CaptureResult> partials, int sessionId, PhysicalCaptureResultInfo physicalResults[])73 public TotalCaptureResult(CameraMetadataNative results, CaptureRequest parent, 74 CaptureResultExtras extras, List<CaptureResult> partials, int sessionId, 75 PhysicalCaptureResultInfo physicalResults[]) { 76 super(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, CaptureResult>(); 87 for (PhysicalCaptureResultInfo onePhysicalResult : physicalResults) { 88 CaptureResult physicalResult = new CaptureResult( 89 onePhysicalResult.getCameraMetadata(), parent, extras); 90 mPhysicalCaptureResults.put(onePhysicalResult.getCameraId(), 91 physicalResult); 92 } 93 } 94 95 /** 96 * Creates a request-less result. 97 * 98 * <p><strong>For testing only.</strong></p> 99 * @hide 100 */ TotalCaptureResult(CameraMetadataNative results, int sequenceId)101 public TotalCaptureResult(CameraMetadataNative results, int sequenceId) { 102 super(results, sequenceId); 103 104 mPartialResults = new ArrayList<>(); 105 mSessionId = CameraCaptureSession.SESSION_ID_NONE; 106 mPhysicalCaptureResults = new HashMap<String, CaptureResult>(); 107 } 108 109 /** 110 * Get the read-only list of partial results that compose this total result. 111 * 112 * <p>The list is returned is unmodifiable; attempting to modify it will result in a 113 * {@code UnsupportedOperationException} being thrown.</p> 114 * 115 * <p>The list size will be inclusive between {@code 0} and 116 * {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT}, with elements in ascending order 117 * of when {@link CameraCaptureSession.CaptureCallback#onCaptureProgressed} was invoked.</p> 118 * 119 * @return unmodifiable list of partial results 120 */ 121 @NonNull getPartialResults()122 public List<CaptureResult> getPartialResults() { 123 return Collections.unmodifiableList(mPartialResults); 124 } 125 126 /** 127 * Get the ID of the session where the capture request of this result was submitted. 128 * 129 * @return The session ID 130 * @hide 131 */ getSessionId()132 public int getSessionId() { 133 return mSessionId; 134 } 135 136 /** 137 * Get the map between physical camera ids and their capture result metadata 138 * 139 * <p>This function can be called for logical multi-camera devices, which are devices that have 140 * REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA capability and calls to {@link 141 * CameraCharacteristics#getPhysicalCameraIds} return a non-empty set of physical devices that 142 * are backing the logical camera.</p> 143 * 144 * <p>If one or more streams from the underlying physical cameras were requested by the 145 * corresponding capture request, this function returns the result metadata for those physical 146 * cameras. Otherwise, an empty map is returned.</p> 147 148 * @return unmodifiable map between physical camera ids and their capture result metadata 149 */ getPhysicalCameraResults()150 public Map<String, CaptureResult> getPhysicalCameraResults() { 151 return Collections.unmodifiableMap(mPhysicalCaptureResults); 152 } 153 } 154