Eino-Ville Talvala | 639fffe | 2015-06-30 10:34:48 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2015 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.params.StreamConfigurationMap; |
| 21 | |
| 22 | import java.util.List; |
| 23 | |
| 24 | /** |
| 25 | * A constrained high speed capture session for a {@link CameraDevice}, used for capturing high |
| 26 | * speed images from the {@link CameraDevice} for high speed video recording use case. |
| 27 | * <p> |
| 28 | * A CameraHighSpeedCaptureSession is created by providing a set of target output surfaces to |
| 29 | * {@link CameraDevice#createConstrainedHighSpeedCaptureSession}, Once created, the session is |
| 30 | * active until a new session is created by the camera device, or the camera device is closed. |
| 31 | * </p> |
| 32 | * <p> |
| 33 | * An active high speed capture session is a specialized capture session that is only targeted at |
| 34 | * high speed video recording (>=120fps) use case if the camera device supports high speed video |
| 35 | * capability (i.e., {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} contains |
| 36 | * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO}). It only |
| 37 | * accepts request lists created via {@link #createHighSpeedRequestList}, and the request list can |
| 38 | * only be submitted to this session via {@link CameraCaptureSession#captureBurst captureBurst}, or |
| 39 | * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}. See |
| 40 | * {@link CameraDevice#createConstrainedHighSpeedCaptureSession} for more details of the |
| 41 | * limitations. |
| 42 | * </p> |
| 43 | * <p> |
| 44 | * Creating a session is an expensive operation and can take several hundred milliseconds, since it |
| 45 | * requires configuring the camera device's internal pipelines and allocating memory buffers for |
| 46 | * sending images to the desired targets. Therefore the setup is done asynchronously, and |
| 47 | * {@link CameraDevice#createConstrainedHighSpeedCaptureSession} will send the ready-to-use |
| 48 | * CameraCaptureSession to the provided listener's |
| 49 | * {@link CameraCaptureSession.StateCallback#onConfigured} callback. If configuration cannot be |
| 50 | * completed, then the {@link CameraCaptureSession.StateCallback#onConfigureFailed} is called, and |
| 51 | * the session will not become active. |
| 52 | * </p> |
| 53 | * <!-- |
| 54 | * <p> |
| 55 | * Any capture requests (repeating or non-repeating) submitted before the session is ready will be |
| 56 | * queued up and will begin capture once the session becomes ready. In case the session cannot be |
| 57 | * configured and {@link CameraCaptureSession.StateCallback#onConfigureFailed onConfigureFailed} is |
| 58 | * called, all queued capture requests are discarded. </p> |
| 59 | * --> |
| 60 | * <p> |
| 61 | * If a new session is created by the camera device, then the previous session is closed, and its |
| 62 | * associated {@link CameraCaptureSession.StateCallback#onClosed onClosed} callback will be |
| 63 | * invoked. All of the session methods will throw an IllegalStateException if called once the |
| 64 | * session is closed. |
| 65 | * </p> |
| 66 | * <p> |
| 67 | * A closed session clears any repeating requests (as if {@link #stopRepeating} had been called), |
| 68 | * but will still complete all of its in-progress capture requests as normal, before a newly created |
| 69 | * session takes over and reconfigures the camera device. |
| 70 | * </p> |
| 71 | */ |
| 72 | public abstract class CameraConstrainedHighSpeedCaptureSession extends CameraCaptureSession { |
| 73 | |
| 74 | /** |
| 75 | * <p>Create a unmodifiable list of requests that is suitable for constrained high speed capture |
| 76 | * session streaming.</p> |
| 77 | * |
| 78 | * <p>High speed video streaming creates significant performance pressure on the camera device, |
| 79 | * so to achieve efficient high speed streaming, the camera device may have to aggregate |
| 80 | * multiple frames together. This means requests must be sent in batched groups, with all |
| 81 | * requests sharing the same settings. This method takes the list of output target |
| 82 | * Surfaces (subject to the output Surface requirements specified by the constrained high speed |
| 83 | * session) and a {@link CaptureRequest request}, and generates a request list that has the same |
| 84 | * controls for each request. The input {@link CaptureRequest request} must contain the target |
| 85 | * output Surfaces and target high speed FPS range that is one of the |
| 86 | * {@link StreamConfigurationMap#getHighSpeedVideoFpsRangesFor} for the Surface size.</p> |
| 87 | * |
| 88 | * <p>If both preview and recording Surfaces are specified in the {@code request}, the |
| 89 | * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE target FPS range} in the input |
| 90 | * {@link CaptureRequest request} must be a fixed frame rate FPS range, where the |
| 91 | * {@link android.util.Range#getLower minimal FPS} == |
| 92 | * {@link android.util.Range#getUpper() maximum FPS}. The created request list will contain |
| 93 | * a interleaved request pattern such that the preview output FPS is at least 30fps, the |
| 94 | * recording output FPS is {@link android.util.Range#getUpper() maximum FPS} of the requested |
| 95 | * FPS range. The application can submit this request list directly to an active high speed |
| 96 | * capture session to achieve high speed video recording. When only preview or recording |
| 97 | * Surface is specified, this method will return a list of request that have the same controls |
| 98 | * and output targets for all requests.</p> |
| 99 | * |
| 100 | * <p>Submitting a request list created by this method to a normal capture session will result |
| 101 | * in an {@link IllegalArgumentException} if the high speed |
| 102 | * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS range} is not supported by |
| 103 | * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES}.</p> |
| 104 | * |
| 105 | * @param request The high speed capture request that will be used to generate the high speed |
| 106 | * request list. |
| 107 | * @return A unmodifiable CaptureRequest list that is suitable for constrained high speed |
| 108 | * capture. |
| 109 | * |
| 110 | * @throws IllegalArgumentException if the set of output Surfaces in the request do not meet the |
| 111 | * high speed video capability requirements, or the camera |
| 112 | * device doesn't support high speed video capability, or the |
| 113 | * request doesn't meet the high speed video capability |
| 114 | * requirements, or the request doesn't contain the required |
| 115 | * controls for high speed capture. |
| 116 | * @throws CameraAccessException if the camera device is no longer connected or has |
| 117 | * encountered a fatal error |
| 118 | * @throws IllegalStateException if the camera device has been closed |
| 119 | * |
| 120 | * @see CameraDevice#createConstrainedHighSpeedCaptureSession |
| 121 | * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE |
| 122 | * @see android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes |
| 123 | * @see android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRangesFor |
| 124 | * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES |
| 125 | * @see CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO |
| 126 | */ |
| 127 | @NonNull |
| 128 | public abstract List<CaptureRequest> createHighSpeedRequestList( |
| 129 | @NonNull CaptureRequest request) throws CameraAccessException; |
| 130 | |
| 131 | } |