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