1 /* 2 * Copyright 2019 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.hardware.camera2.CameraCaptureSession; 20 import android.hardware.camera2.CameraDevice; 21 22 import android.annotation.IntDef; 23 import android.annotation.NonNull; 24 25 import java.lang.annotation.Retention; 26 import java.lang.annotation.RetentionPolicy; 27 28 /** 29 * A camera capture session that was switched to offline mode via successful call to 30 * {@link CameraCaptureSession#switchToOffline}. 31 * 32 * <p>Offline capture sessions allow clients to select a set of camera registered surfaces that 33 * support offline mode. After a successful offline mode switch all non-repeating pending requests 34 * on those surfaces will continue to be processed by the camera stack even if clients close the 35 * corresponding camera device.<p> 36 * 37 * <p>Offline capture session instances will replace the previously active capture session arguments 38 * in all capture callbacks after {@link CameraCaptureSession#switchToOffline} completes.</p> 39 * 40 * <p>Processing of pending offline capture requests will begin only after the offline session 41 * moves to ready state which will be indicated by the {@link CameraOfflineSessionCallback#onReady} 42 * callback.</p> 43 * 44 * <p>In contrast to a regular {@link CameraCaptureSession} an offline capture session will 45 * not accept any further capture requests. Besides {@link CameraOfflineSession#close} all 46 * remaining methods will throw {@link UnsupportedOperationException} and are not supported.</p> 47 * 48 * @see CameraCaptureSession#supportsOfflineProcessing 49 */ 50 public abstract class CameraOfflineSession extends CameraCaptureSession { 51 public static abstract class CameraOfflineSessionCallback { 52 /** 53 * This method indicates that the offline switch call 54 * {@link CameraCaptureSession#switchToOffline} was successful. 55 * 56 * <p>This callback will be invoked once the offline session moves to the ready state.</p> 57 * 58 * <p>Calls to {@link CameraDevice#close} will not have impact on the processing of offline 59 * requests once the offline session moves in ready state.</p> 60 * 61 * @param session the currently ready offline session 62 * 63 */ onReady(@onNull CameraOfflineSession session)64 public abstract void onReady(@NonNull CameraOfflineSession session); 65 66 /** 67 * This method indicates that the offline switch call 68 * {@link CameraCaptureSession#switchToOffline} was not able to complete successfully. 69 * 70 * <p>The offline switch can fail either due to internal camera error during the switch 71 * sequence or because the camera implementation was not able to find any pending capture 72 * requests that can be migrated to offline mode.</p> 73 * 74 * <p>Calling {@link CameraOfflineSession#close} is not necessary and clients will not 75 * receive any further offline session notifications.</p> 76 * 77 * @param session the offline session that failed to switch to ready state 78 */ onSwitchFailed(@onNull CameraOfflineSession session)79 public abstract void onSwitchFailed(@NonNull CameraOfflineSession session); 80 81 /** 82 * This method indicates that all pending offline requests were processed. 83 * 84 * <p>This callback will be invoked once the offline session finishes processing 85 * all of its pending offline capture requests.</p> 86 * 87 * @param session the currently ready offline session 88 * 89 */ onIdle(@onNull CameraOfflineSession session)90 public abstract void onIdle(@NonNull CameraOfflineSession session); 91 92 /** 93 * This status code indicates unexpected and fatal internal camera error. 94 * 95 * <p>Pending offline requests will be discarded and the respective registered 96 * capture callbacks may not get triggered.</p> 97 * 98 * @see #onError 99 */ 100 public static final int STATUS_INTERNAL_ERROR = 0; 101 102 /** @hide */ 103 @Retention(RetentionPolicy.SOURCE) 104 @IntDef(prefix = {"STATUS_"}, value = {STATUS_INTERNAL_ERROR}) 105 public @interface StatusCode {}; 106 107 /** 108 * This method is called when the offline session encounters an unexpected error. 109 * 110 * <p>This notification will only be invoked for sessions that reached the ready state. 111 * Clients will need to call {@link CameraOfflineSession#close} to close and release all 112 * resources. {@link #onClosed} will not be triggered automatically in error scenarios.</p> 113 * 114 * @param session the current offline session 115 * @param status error status 116 * 117 */ onError(@onNull CameraOfflineSession session, @StatusCode int status)118 public abstract void onError(@NonNull CameraOfflineSession session, @StatusCode int status); 119 120 /** 121 * This method is called when the offline session is closed. 122 * 123 * <p>An offline session will be closed after a call to 124 * {@link CameraOfflineSession#close}.</p> 125 * 126 * <p>In case of failure to switch to offline mode, only {@link #onSwitchFailed} will be 127 * called and {@link #onClosed} will not be.</p> 128 * 129 * <p>In case there was no previous {@link #onIdle} notification any in-progress 130 * offline capture requests within the offline session will be discarded 131 * and further result callbacks will not be triggered.</p> 132 * 133 * @param session the session returned by {@link CameraCaptureSession#switchToOffline} 134 * 135 */ onClosed(@onNull CameraOfflineSession session)136 public abstract void onClosed(@NonNull CameraOfflineSession session); 137 } 138 139 /** 140 * Close this offline capture session. 141 * 142 * <p>Abort all pending offline requests and close the connection to the offline camera session 143 * as quickly as possible.</p> 144 * 145 * <p>This method can be called only after clients receive 146 * {@link CameraOfflineSessionCallback#onReady}.</p> 147 * 148 * <p>Immediately after this call, besides the final 149 * {@link CameraOfflineSessionCallback#onClosed} notification, no further callbacks from the 150 * offline session will be triggered and all remaining offline capture requests will be 151 * discarded.</p> 152 * 153 * <p>Closing a session is idempotent; closing more than once has no effect.</p> 154 * 155 * @throws IllegalStateException if the offline sesion is not ready. 156 */ 157 @Override close()158 public abstract void close(); 159 } 160