1 /* 2 * Copyright 2021 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 androidx.camera.camera2.internal; 18 19 import android.hardware.camera2.CameraCaptureSession; 20 import android.hardware.camera2.CameraDevice; 21 import android.hardware.camera2.CaptureRequest; 22 23 import androidx.camera.core.impl.CaptureConfig; 24 import androidx.camera.core.impl.DeferrableSurface; 25 import androidx.camera.core.impl.SessionConfig; 26 27 import com.google.common.util.concurrent.ListenableFuture; 28 29 import org.jspecify.annotations.NonNull; 30 import org.jspecify.annotations.Nullable; 31 32 import java.util.List; 33 import java.util.Map; 34 35 /** 36 * An interface for manipulating the session to capture images from the camera which is tied to a 37 * specific {@link CameraDevice}. 38 * 39 * <p>A session can only be opened a single time. Once has {@link CaptureSessionInterface 40 * #close()} been called then it is permanently closed so a new session has to be created for 41 * capturing images. 42 */ 43 interface CaptureSessionInterface { 44 /** 45 * Opens the capture session. 46 * 47 * <p>When the session is opened and the configurations have been set then the capture requests 48 * will be issued. 49 * 50 * <p>The cancellation of the returned ListenableFuture will not propagate into the inner 51 * future, that is, the capture session creation process is not cancelable. 52 * 53 * @param sessionConfig which is used to configure the camera capture session. 54 * This contains configurations which may or may not be currently 55 * active in issuing capture requests. 56 * @param cameraDevice the camera with which to generate the capture session 57 * @param opener The opener to open the {@link SynchronizedCaptureSession}. 58 * @return A {@link ListenableFuture} that will be completed once the 59 * {@link CameraCaptureSession} has been configured. 60 * It may be set to a {@link java.util.concurrent.CancellationException} if a CaptureSession 61 * is closed while it is opening. 62 * It may be set to a {@link DeferrableSurface.SurfaceClosedException} if any of the supplied 63 * DeferrableSurface is closed that cannot be used to configure the 64 * {@link CameraCaptureSession}. 65 */ open(@onNull SessionConfig sessionConfig, @NonNull CameraDevice cameraDevice, SynchronizedCaptureSession.@NonNull Opener opener)66 @NonNull ListenableFuture<Void> open(@NonNull SessionConfig sessionConfig, 67 @NonNull CameraDevice cameraDevice, 68 SynchronizedCaptureSession.@NonNull Opener opener); 69 70 71 /** 72 * Sets the active configurations for the capture session. 73 * 74 * <p>Once both the session configuration has been set and the session has been opened, then the 75 * repeating capture requests will immediately be issued. 76 * 77 * @param sessionConfig has the configuration that will currently active in issuing capture 78 * request. The surfaces contained in this must be a subset of the 79 * surfaces that were used to open this capture session. 80 */ setSessionConfig(@ullable SessionConfig sessionConfig)81 void setSessionConfig(@Nullable SessionConfig sessionConfig); 82 83 /** 84 * Returns the configurations of the capture session, or null if it has not yet been set 85 * or if the capture session has been closed. 86 */ getSessionConfig()87 @Nullable SessionConfig getSessionConfig(); 88 89 /** Returns the configurations of the capture requests. */ getCaptureConfigs()90 @NonNull List<CaptureConfig> getCaptureConfigs(); 91 92 /** 93 * Issues capture requests. 94 * 95 * @param captureConfigs which is used to construct {@link CaptureRequest}. 96 */ issueCaptureRequests(@onNull List<CaptureConfig> captureConfigs)97 void issueCaptureRequests(@NonNull List<CaptureConfig> captureConfigs); 98 99 /** 100 * Cancels issued capture requests. 101 */ cancelIssuedCaptureRequests()102 void cancelIssuedCaptureRequests(); 103 104 /** 105 * Closes the capture session. 106 * 107 * <p>Close() needs be called on a session in order to safely open another session. However, 108 * this stops minimal resources so that another session can be quickly opened. 109 * 110 * <p>Once a session is closed it can no longer be opened again. After the session is closed all 111 * method calls on it do nothing. 112 */ close()113 void close(); 114 115 /** 116 * Releases the capture session. 117 * 118 * <p>This releases all of the sessions resources and should be called when ready to close the 119 * camera. 120 * 121 * <p>Once a session is released it can no longer be opened again. After the session is released 122 * all method calls on it do nothing. 123 */ release(boolean abortInFlightCaptures)124 @NonNull ListenableFuture<Void> release(boolean abortInFlightCaptures); 125 126 /** 127 * Sets the mapping relations between surfaces and the streamUseCases of their associated 128 * streams 129 * 130 * @param streamUseCaseMap the mapping between surfaces and the streamUseCase flag of the 131 * associated streams 132 */ setStreamUseCaseMap(@onNull Map<DeferrableSurface, Long> streamUseCaseMap)133 void setStreamUseCaseMap(@NonNull Map<DeferrableSurface, Long> streamUseCaseMap); 134 135 /** 136 * Checks if the capture session has been successfully opened or is in the process of being 137 * opened. 138 * 139 * @return true if the capture session is in an open state; otherwise, false. 140 */ isInOpenState()141 boolean isInOpenState(); 142 } 143