1/*
2 * Copyright (C) 2012 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 com.android.camera;
18
19import android.annotation.TargetApi;
20import android.graphics.SurfaceTexture;
21import android.hardware.Camera;
22import android.hardware.Camera.ErrorCallback;
23import android.hardware.Camera.OnZoomChangeListener;
24import android.hardware.Camera.Parameters;
25import android.os.Build;
26import android.os.Handler;
27import android.view.SurfaceHolder;
28
29/**
30 * An interface which provides possible camera device operations.
31 *
32 * The client should call {@code CameraManager.cameraOpen} to get an instance
33 * of {@link CameraManager.CameraProxy} to control the camera. Classes
34 * implementing this interface should have its own one unique {@code Thread}
35 * other than the main thread for camera operations. Camera device callbacks
36 * are wrapped since the client should not deal with
37 * {@code android.hardware.Camera} directly.
38 *
39 * TODO: provide callback interfaces for:
40 * {@code android.hardware.Camera.ErrorCallback},
41 * {@code android.hardware.Camera.OnZoomChangeListener}, and
42 * {@code android.hardware.Camera.Parameters}.
43 */
44public interface CameraManager {
45
46    /**
47     * An interface which wraps
48     * {@link android.hardware.Camera.AutoFocusCallback}.
49     */
50    public interface CameraAFCallback {
51        public void onAutoFocus(boolean focused, CameraProxy camera);
52    }
53
54    /**
55     * An interface which wraps
56     * {@link android.hardware.Camera.AutoFocusMoveCallback}.
57     */
58    public interface CameraAFMoveCallback {
59        public void onAutoFocusMoving(boolean moving, CameraProxy camera);
60    }
61
62    /**
63     * An interface which wraps
64     * {@link android.hardware.Camera.ShutterCallback}.
65     */
66    public interface CameraShutterCallback {
67        public void onShutter(CameraProxy camera);
68    }
69
70    /**
71     * An interface which wraps
72     * {@link android.hardware.Camera.PictureCallback}.
73     */
74    public interface CameraPictureCallback {
75        public void onPictureTaken(byte[] data, CameraProxy camera);
76    }
77
78    /**
79     * An interface which wraps
80     * {@link android.hardware.Camera.PreviewCallback}.
81     */
82    public interface CameraPreviewDataCallback {
83        public void onPreviewFrame(byte[] data, CameraProxy camera);
84    }
85
86    /**
87     * An interface which wraps
88     * {@link android.hardware.Camera.FaceDetectionListener}.
89     */
90    public interface CameraFaceDetectionCallback {
91        /**
92         * Callback for face detection.
93         *
94         * @param faces   Recognized face in the preview.
95         * @param camera  The camera which the preview image comes from.
96         */
97        public void onFaceDetection(Camera.Face[] faces, CameraProxy camera);
98    }
99
100    /**
101     * An interface to be called for any exception caught when opening the
102     * camera device. This error callback is different from the one defined
103     * in the framework, {@link android.hardware.Camera.ErrorCallback}, which
104     * is used after the camera is opened.
105     */
106    public interface CameraOpenErrorCallback {
107        /**
108         * Callback when {@link com.android.camera.CameraDisabledException} is
109         * caught.
110         *
111         * @param cameraId The disabled camera.
112         */
113        public void onCameraDisabled(int cameraId);
114
115        /**
116         * Callback when {@link com.android.camera.CameraHardwareException} is
117         * caught.
118         *
119         * @param cameraId The camera with the hardware failure.
120         */
121        public void onDeviceOpenFailure(int cameraId);
122
123        /**
124         * Callback when {@link java.io.IOException} is caught during
125         * {@link android.hardware.Camera#reconnect()}.
126         *
127         * @param mgr The {@link com.android.camera.CameraManager}
128         *            with the reconnect failure.
129         */
130        public void onReconnectionFailure(CameraManager mgr);
131    }
132
133    /**
134     * Opens the camera of the specified ID synchronously.
135     *
136     * @param handler The {@link android.os.Handler} in which the callback
137     *                was handled.
138     * @param callback The callback when any error happens.
139     * @param cameraId The camera ID to open.
140     * @return   An instance of {@link CameraProxy} on success. null on failure.
141     */
142    public CameraProxy cameraOpen(
143            Handler handler, int cameraId, CameraOpenErrorCallback callback);
144
145    /**
146     * An interface that takes camera operation requests and post messages to the
147     * camera handler thread. All camera operations made through this interface is
148     * asynchronous by default except those mentioned specifically.
149     */
150    public interface CameraProxy {
151
152        /**
153         * Returns the underlying {@link android.hardware.Camera} object used
154         * by this proxy. This method should only be used when handing the
155         * camera device over to {@link android.media.MediaRecorder} for
156         * recording.
157         */
158        public android.hardware.Camera getCamera();
159
160        /**
161         * Releases the camera device synchronously.
162         * This function must be synchronous so the caller knows exactly when the camera
163         * is released and can continue on.
164         */
165        public void release();
166
167        /**
168         * Reconnects to the camera device.
169         * @see android.hardware.Camera#reconnect()
170         *
171         * @param handler The {@link android.os.Handler} in which the callback
172         *                was handled.
173         * @param cb The callback when any error happens.
174         * @return {@code false} on errors.
175         */
176        public boolean reconnect(Handler handler, CameraOpenErrorCallback cb);
177
178        /**
179         * Unlocks the camera device.
180         *
181         * @see android.hardware.Camera#unlock()
182         */
183        public void unlock();
184
185        /**
186         * Locks the camera device.
187         * @see android.hardware.Camera#lock()
188         */
189        public void lock();
190
191        /**
192         * Sets the {@link android.graphics.SurfaceTexture} for preview.
193         *
194         * @param surfaceTexture The {@link SurfaceTexture} for preview.
195         */
196        public void setPreviewTexture(final SurfaceTexture surfaceTexture);
197
198        /**
199         * Sets the {@link android.view.SurfaceHolder} for preview.
200         *
201         * @param surfaceHolder The {@link SurfaceHolder} for preview.
202         */
203        public void setPreviewDisplay(final SurfaceHolder surfaceHolder);
204
205        /**
206         * Starts the camera preview.
207         */
208        public void startPreview();
209
210        /**
211         * Stops the camera preview synchronously.
212         * {@code stopPreview()} must be synchronous to ensure that the caller can
213         * continues to release resources related to camera preview.
214         */
215        public void stopPreview();
216
217        /**
218         * Sets the callback for preview data.
219         *
220         * @param handler    The {@link android.os.Handler} in which the callback was handled.
221         * @param cb         The callback to be invoked when the preview data is available.
222         * @see  android.hardware.Camera#setPreviewCallback(android.hardware.Camera.PreviewCallback)
223         */
224        public void setPreviewDataCallback(Handler handler, CameraPreviewDataCallback cb);
225
226        /**
227         * Sets the callback for preview data.
228         *
229         * @param handler The handler in which the callback will be invoked.
230         * @param cb      The callback to be invoked when the preview data is available.
231         * @see android.hardware.Camera#setPreviewCallbackWithBuffer(android.hardware.Camera.PreviewCallback)
232         */
233        public void setPreviewDataCallbackWithBuffer(Handler handler, CameraPreviewDataCallback cb);
234
235        /**
236         * Adds buffer for the preview callback.
237         *
238         * @param callbackBuffer The buffer allocated for the preview data.
239         */
240        public void addCallbackBuffer(byte[] callbackBuffer);
241
242        /**
243         * Starts the auto-focus process. The result will be returned through the callback.
244         *
245         * @param handler The handler in which the callback will be invoked.
246         * @param cb      The auto-focus callback.
247         */
248        public void autoFocus(Handler handler, CameraAFCallback cb);
249
250        /**
251         * Cancels the auto-focus process.
252         */
253        public void cancelAutoFocus();
254
255        /**
256         * Sets the auto-focus callback
257         *
258         * @param handler The handler in which the callback will be invoked.
259         * @param cb      The callback to be invoked when the preview data is available.
260         */
261        @TargetApi(Build.VERSION_CODES.JELLY_BEAN)
262        public void setAutoFocusMoveCallback(Handler handler, CameraAFMoveCallback cb);
263
264        /**
265         * Instrument the camera to take a picture.
266         *
267         * @param handler   The handler in which the callback will be invoked.
268         * @param shutter   The callback for shutter action, may be null.
269         * @param raw       The callback for uncompressed data, may be null.
270         * @param postview  The callback for postview image data, may be null.
271         * @param jpeg      The callback for jpeg image data, may be null.
272         * @see android.hardware.Camera#takePicture(
273         *         android.hardware.Camera.ShutterCallback,
274         *         android.hardware.Camera.PictureCallback,
275         *         android.hardware.Camera.PictureCallback)
276         */
277        public void takePicture(
278                Handler handler,
279                CameraShutterCallback shutter,
280                CameraPictureCallback raw,
281                CameraPictureCallback postview,
282                CameraPictureCallback jpeg);
283
284        /**
285         * Sets the display orientation for camera to adjust the preview orientation.
286         *
287         * @param degrees The rotation in degrees. Should be 0, 90, 180 or 270.
288         */
289        public void setDisplayOrientation(int degrees);
290
291        /**
292         * Sets the listener for zoom change.
293         *
294         * @param listener The listener.
295         */
296        public void setZoomChangeListener(OnZoomChangeListener listener);
297
298        /**
299         * Sets the face detection listener.
300         *
301         * @param handler  The handler in which the callback will be invoked.
302         * @param callback The callback for face detection results.
303         */
304        public void setFaceDetectionCallback(Handler handler, CameraFaceDetectionCallback callback);
305
306        /**
307         * Starts the face detection.
308         */
309        public void startFaceDetection();
310
311        /**
312         * Stops the face detection.
313         */
314        public void stopFaceDetection();
315
316        /**
317         * Registers an error callback.
318         *
319         * @param cb The error callback.
320         * @see android.hardware.Camera#setErrorCallback(android.hardware.Camera.ErrorCallback)
321         */
322        public void setErrorCallback(ErrorCallback cb);
323
324        /**
325         * Sets the camera parameters.
326         *
327         * @param params The camera parameters to use.
328         */
329        public void setParameters(Parameters params);
330
331        /**
332         * Gets the current camera parameters synchronously. This method is
333         * synchronous since the caller has to wait for the camera to return
334         * the parameters. If the parameters are already cached, it returns
335         * immediately.
336         */
337        public Parameters getParameters();
338
339        /**
340         * Forces {@code CameraProxy} to update the cached version of the camera
341         * parameters regardless of the dirty bit.
342         */
343        public void refreshParameters();
344
345        /**
346         * Enables/Disables the camera shutter sound.
347         *
348         * @param enable   {@code true} to enable the shutter sound,
349         *                 {@code false} to disable it.
350         */
351        public void enableShutterSound(boolean enable);
352    }
353}
354