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
17package android.hardware.camera2;
18
19import android.annotation.NonNull;
20import android.hardware.camera2.params.StreamConfigurationMap;
21
22import 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 */
72public 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}
132