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