1639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala/* 2639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Copyright 2015 The Android Open Source Project 3639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 4639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Licensed under the Apache License, Version 2.0 (the "License"); 5639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * you may not use this file except in compliance with the License. 6639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * You may obtain a copy of the License at 7639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 8639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * http://www.apache.org/licenses/LICENSE-2.0 9639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 10639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Unless required by applicable law or agreed to in writing, software 11639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * distributed under the License is distributed on an "AS IS" BASIS, 12639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * See the License for the specific language governing permissions and 14639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * limitations under the License. 15639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala */ 16639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala 17639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvalapackage android.hardware.camera2; 18639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala 19639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvalaimport android.annotation.NonNull; 20639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvalaimport android.hardware.camera2.params.StreamConfigurationMap; 21639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala 22639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvalaimport java.util.List; 23639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala 24639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala/** 25639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * A constrained high speed capture session for a {@link CameraDevice}, used for capturing high 26639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * speed images from the {@link CameraDevice} for high speed video recording use case. 27639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p> 28639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * A CameraHighSpeedCaptureSession is created by providing a set of target output surfaces to 29639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraDevice#createConstrainedHighSpeedCaptureSession}, Once created, the session is 30639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * active until a new session is created by the camera device, or the camera device is closed. 31639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * </p> 32639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p> 33639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * An active high speed capture session is a specialized capture session that is only targeted at 34639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * high speed video recording (>=120fps) use case if the camera device supports high speed video 35639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * capability (i.e., {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} contains 36639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO}). It only 37639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * accepts request lists created via {@link #createHighSpeedRequestList}, and the request list can 38639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * only be submitted to this session via {@link CameraCaptureSession#captureBurst captureBurst}, or 39639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}. See 40639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraDevice#createConstrainedHighSpeedCaptureSession} for more details of the 41639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * limitations. 42639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * </p> 43639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p> 44639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Creating a session is an expensive operation and can take several hundred milliseconds, since it 45639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * requires configuring the camera device's internal pipelines and allocating memory buffers for 46639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * sending images to the desired targets. Therefore the setup is done asynchronously, and 47639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraDevice#createConstrainedHighSpeedCaptureSession} will send the ready-to-use 48639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * CameraCaptureSession to the provided listener's 49639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraCaptureSession.StateCallback#onConfigured} callback. If configuration cannot be 50639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * completed, then the {@link CameraCaptureSession.StateCallback#onConfigureFailed} is called, and 51639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * the session will not become active. 52639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * </p> 53639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <!-- 54639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p> 55639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Any capture requests (repeating or non-repeating) submitted before the session is ready will be 56639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * queued up and will begin capture once the session becomes ready. In case the session cannot be 57639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * configured and {@link CameraCaptureSession.StateCallback#onConfigureFailed onConfigureFailed} is 58639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * called, all queued capture requests are discarded. </p> 59639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * --> 60639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p> 61639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * If a new session is created by the camera device, then the previous session is closed, and its 62639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * associated {@link CameraCaptureSession.StateCallback#onClosed onClosed} callback will be 63639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * invoked. All of the session methods will throw an IllegalStateException if called once the 64639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * session is closed. 65639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * </p> 66639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p> 67639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * A closed session clears any repeating requests (as if {@link #stopRepeating} had been called), 68639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * but will still complete all of its in-progress capture requests as normal, before a newly created 69639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * session takes over and reconfigures the camera device. 70639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * </p> 71639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala */ 72639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvalapublic abstract class CameraConstrainedHighSpeedCaptureSession extends CameraCaptureSession { 73639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala 74639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala /** 75639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p>Create a unmodifiable list of requests that is suitable for constrained high speed capture 76639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * session streaming.</p> 77639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 78639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p>High speed video streaming creates significant performance pressure on the camera device, 79639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * so to achieve efficient high speed streaming, the camera device may have to aggregate 80639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * multiple frames together. This means requests must be sent in batched groups, with all 81639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * requests sharing the same settings. This method takes the list of output target 82639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Surfaces (subject to the output Surface requirements specified by the constrained high speed 83639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * session) and a {@link CaptureRequest request}, and generates a request list that has the same 84639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * controls for each request. The input {@link CaptureRequest request} must contain the target 85639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * output Surfaces and target high speed FPS range that is one of the 86639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link StreamConfigurationMap#getHighSpeedVideoFpsRangesFor} for the Surface size.</p> 87639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 88639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p>If both preview and recording Surfaces are specified in the {@code request}, the 89639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE target FPS range} in the input 90639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CaptureRequest request} must be a fixed frame rate FPS range, where the 91639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link android.util.Range#getLower minimal FPS} == 92639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link android.util.Range#getUpper() maximum FPS}. The created request list will contain 93639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * a interleaved request pattern such that the preview output FPS is at least 30fps, the 94639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * recording output FPS is {@link android.util.Range#getUpper() maximum FPS} of the requested 95639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * FPS range. The application can submit this request list directly to an active high speed 96639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * capture session to achieve high speed video recording. When only preview or recording 97639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * Surface is specified, this method will return a list of request that have the same controls 98639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * and output targets for all requests.</p> 99639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 100639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * <p>Submitting a request list created by this method to a normal capture session will result 101639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * in an {@link IllegalArgumentException} if the high speed 102639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS range} is not supported by 103639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES}.</p> 104639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 105639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @param request The high speed capture request that will be used to generate the high speed 106639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * request list. 107639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @return A unmodifiable CaptureRequest list that is suitable for constrained high speed 108639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * capture. 109639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 110639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @throws IllegalArgumentException if the set of output Surfaces in the request do not meet the 111639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * high speed video capability requirements, or the camera 112639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * device doesn't support high speed video capability, or the 113639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * request doesn't meet the high speed video capability 114639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * requirements, or the request doesn't contain the required 115639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * controls for high speed capture. 116639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @throws CameraAccessException if the camera device is no longer connected or has 117639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * encountered a fatal error 118639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @throws IllegalStateException if the camera device has been closed 119639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * 120639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @see CameraDevice#createConstrainedHighSpeedCaptureSession 121639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE 122639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @see android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes 123639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @see android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRangesFor 124639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES 125639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala * @see CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO 126639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala */ 127639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala @NonNull 128639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala public abstract List<CaptureRequest> createHighSpeedRequestList( 129639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala @NonNull CaptureRequest request) throws CameraAccessException; 130639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala 131639fffee624302ec5b175503d7bd8a441340a629Eino-Ville Talvala} 132