1/*
2 * Copyright (C) 2008 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#ifndef ANDROID_HARDWARE_CAMERA_HARDWARE_INTERFACE_H
18#define ANDROID_HARDWARE_CAMERA_HARDWARE_INTERFACE_H
19
20#include <binder/IMemory.h>
21#include <utils/RefBase.h>
22#include <surfaceflinger/ISurface.h>
23#include <camera/Camera.h>
24#include <camera/CameraParameters.h>
25
26namespace android {
27
28class Overlay;
29
30/**
31 *  The size of image for display.
32 */
33typedef struct image_rect_struct
34{
35  uint32_t width;      /* Image width */
36  uint32_t height;     /* Image height */
37} image_rect_type;
38
39
40typedef void (*notify_callback)(int32_t msgType,
41                                int32_t ext1,
42                                int32_t ext2,
43                                void* user);
44
45typedef void (*data_callback)(int32_t msgType,
46                              const sp<IMemory>& dataPtr,
47                              void* user);
48
49typedef void (*data_callback_timestamp)(nsecs_t timestamp,
50                                        int32_t msgType,
51                                        const sp<IMemory>& dataPtr,
52                                        void* user);
53
54/**
55 * CameraHardwareInterface.h defines the interface to the
56 * camera hardware abstraction layer, used for setting and getting
57 * parameters, live previewing, and taking pictures.
58 *
59 * It is a referenced counted interface with RefBase as its base class.
60 * CameraService calls openCameraHardware() to retrieve a strong pointer to the
61 * instance of this interface and may be called multiple times. The
62 * following steps describe a typical sequence:
63 *
64 *   -# After CameraService calls openCameraHardware(), getParameters() and
65 *      setParameters() are used to initialize the camera instance.
66 *      CameraService calls getPreviewHeap() to establish access to the
67 *      preview heap so it can be registered with SurfaceFlinger for
68 *      efficient display updating while in preview mode.
69 *   -# startPreview() is called.  The camera instance then periodically
70 *      sends the message CAMERA_MSG_PREVIEW_FRAME (if enabled) each time
71 *      a new preview frame is available.  If data callback code needs to use
72 *      this memory after returning, it must copy the data.
73 *
74 * Prior to taking a picture, CameraService calls autofocus(). When auto
75 * focusing has completed, the camera instance sends a CAMERA_MSG_FOCUS notification,
76 * which informs the application whether focusing was successful. The camera instance
77 * only sends this message once and it is up  to the application to call autoFocus()
78 * again if refocusing is desired.
79 *
80 * CameraService calls takePicture() to request the camera instance take a
81 * picture. At this point, if a shutter, postview, raw, and/or compressed callback
82 * is desired, the corresponding message must be enabled. As with CAMERA_MSG_PREVIEW_FRAME,
83 * any memory provided in a data callback must be copied if it's needed after returning.
84 */
85class CameraHardwareInterface : public virtual RefBase {
86public:
87    virtual ~CameraHardwareInterface() { }
88
89    /** Return the IMemoryHeap for the preview image heap */
90    virtual sp<IMemoryHeap>         getPreviewHeap() const = 0;
91
92    /** Return the IMemoryHeap for the raw image heap */
93    virtual sp<IMemoryHeap>         getRawHeap() const = 0;
94
95    /** Set the notification and data callbacks */
96    virtual void setCallbacks(notify_callback notify_cb,
97                              data_callback data_cb,
98                              data_callback_timestamp data_cb_timestamp,
99                              void* user) = 0;
100
101    /**
102     * The following three functions all take a msgtype,
103     * which is a bitmask of the messages defined in
104     * include/ui/Camera.h
105     */
106
107    /**
108     * Enable a message, or set of messages.
109     */
110    virtual void        enableMsgType(int32_t msgType) = 0;
111
112    /**
113     * Disable a message, or a set of messages.
114     */
115    virtual void        disableMsgType(int32_t msgType) = 0;
116
117    /**
118     * Query whether a message, or a set of messages, is enabled.
119     * Note that this is operates as an AND, if any of the messages
120     * queried are off, this will return false.
121     */
122    virtual bool        msgTypeEnabled(int32_t msgType) = 0;
123
124    /**
125     * Start preview mode.
126     */
127    virtual status_t    startPreview() = 0;
128
129    /**
130     * Only used if overlays are used for camera preview.
131     */
132    virtual bool         useOverlay() {return false;}
133    virtual status_t     setOverlay(const sp<Overlay> &overlay) {return BAD_VALUE;}
134
135    /**
136     * Stop a previously started preview.
137     */
138    virtual void        stopPreview() = 0;
139
140    /**
141     * Returns true if preview is enabled.
142     */
143    virtual bool        previewEnabled() = 0;
144
145    /**
146     * Start record mode. When a record image is available a CAMERA_MSG_VIDEO_FRAME
147     * message is sent with the corresponding frame. Every record frame must be released
148     * by calling releaseRecordingFrame().
149     */
150    virtual status_t    startRecording() = 0;
151
152    /**
153     * Stop a previously started recording.
154     */
155    virtual void        stopRecording() = 0;
156
157    /**
158     * Returns true if recording is enabled.
159     */
160    virtual bool        recordingEnabled() = 0;
161
162    /**
163     * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME.
164     */
165    virtual void        releaseRecordingFrame(const sp<IMemory>& mem) = 0;
166
167    /**
168     * Start auto focus, the notification callback routine is called
169     * with CAMERA_MSG_FOCUS once when focusing is complete. autoFocus()
170     * will be called again if another auto focus is needed.
171     */
172    virtual status_t    autoFocus() = 0;
173
174    /**
175     * Cancels auto-focus function. If the auto-focus is still in progress,
176     * this function will cancel it. Whether the auto-focus is in progress
177     * or not, this function will return the focus position to the default.
178     * If the camera does not support auto-focus, this is a no-op.
179     */
180    virtual status_t    cancelAutoFocus() = 0;
181
182    /**
183     * Take a picture.
184     */
185    virtual status_t    takePicture() = 0;
186
187    /**
188     * Cancel a picture that was started with takePicture.  Calling this
189     * method when no picture is being taken is a no-op.
190     */
191    virtual status_t    cancelPicture() = 0;
192
193    /** Set the camera parameters. */
194    virtual status_t    setParameters(const CameraParameters& params) = 0;
195
196    /** Return the camera parameters. */
197    virtual CameraParameters  getParameters() const = 0;
198
199    /**
200     * Send command to camera driver.
201     */
202    virtual status_t sendCommand(int32_t cmd, int32_t arg1, int32_t arg2) = 0;
203
204    /**
205     * Release the hardware resources owned by this object.  Note that this is
206     * *not* done in the destructor.
207     */
208    virtual void release() = 0;
209
210    /**
211     * Dump state of the camera hardware
212     */
213    virtual status_t dump(int fd, const Vector<String16>& args) const = 0;
214};
215
216/** factory function to instantiate a camera hardware object */
217extern "C" sp<CameraHardwareInterface> openCameraHardware();
218
219};  // namespace android
220
221#endif
222