1/*
2 * Copyright (C) 2010-2011 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_INCLUDE_CAMERA_H
18#define ANDROID_INCLUDE_CAMERA_H
19
20#include "camera_common.h"
21
22/**
23 * Camera device HAL, initial version [ CAMERA_DEVICE_API_VERSION_1_0 ]
24 *
25 * DEPRECATED. New devices should use Camera HAL v3.2 or newer.
26 *
27 * Supports the android.hardware.Camera API, and the android.hardware.camera2
28 * API in legacy mode only.
29 *
30 * Camera devices that support this version of the HAL must return a value in
31 * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in
32 * camera_device_t.common.version. CAMERA_DEVICE_API_VERSION_1_0 is the
33 * recommended value.
34 *
35 * Camera modules that implement version 2.0 or higher of camera_module_t must
36 * also return the value of camera_device_t.common.version in
37 * camera_info_t.device_version.
38 *
39 * See camera_common.h for more details.
40 */
41
42__BEGIN_DECLS
43
44struct camera_memory;
45typedef void (*camera_release_memory)(struct camera_memory *mem);
46
47typedef struct camera_memory {
48    void *data;
49    size_t size;
50    void *handle;
51    camera_release_memory release;
52} camera_memory_t;
53
54typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs,
55                                                  void *user);
56
57typedef void (*camera_notify_callback)(int32_t msg_type,
58        int32_t ext1,
59        int32_t ext2,
60        void *user);
61
62typedef void (*camera_data_callback)(int32_t msg_type,
63        const camera_memory_t *data, unsigned int index,
64        camera_frame_metadata_t *metadata, void *user);
65
66typedef void (*camera_data_timestamp_callback)(int64_t timestamp,
67        int32_t msg_type,
68        const camera_memory_t *data, unsigned int index,
69        void *user);
70
71#define HAL_CAMERA_PREVIEW_WINDOW_TAG 0xcafed00d
72
73typedef struct preview_stream_ops {
74    int (*dequeue_buffer)(struct preview_stream_ops* w,
75                          buffer_handle_t** buffer, int *stride);
76    int (*enqueue_buffer)(struct preview_stream_ops* w,
77                buffer_handle_t* buffer);
78    int (*cancel_buffer)(struct preview_stream_ops* w,
79                buffer_handle_t* buffer);
80    int (*set_buffer_count)(struct preview_stream_ops* w, int count);
81    int (*set_buffers_geometry)(struct preview_stream_ops* pw,
82                int w, int h, int format);
83    int (*set_crop)(struct preview_stream_ops *w,
84                int left, int top, int right, int bottom);
85    int (*set_usage)(struct preview_stream_ops* w, int usage);
86    int (*set_swap_interval)(struct preview_stream_ops *w, int interval);
87    int (*get_min_undequeued_buffer_count)(const struct preview_stream_ops *w,
88                int *count);
89    int (*lock_buffer)(struct preview_stream_ops* w,
90                buffer_handle_t* buffer);
91    // Timestamps are measured in nanoseconds, and must be comparable
92    // and monotonically increasing between two frames in the same
93    // preview stream. They do not need to be comparable between
94    // consecutive or parallel preview streams, cameras, or app runs.
95    int (*set_timestamp)(struct preview_stream_ops *w, int64_t timestamp);
96} preview_stream_ops_t;
97
98struct camera_device;
99typedef struct camera_device_ops {
100    /** Set the ANativeWindow to which preview frames are sent */
101    int (*set_preview_window)(struct camera_device *,
102            struct preview_stream_ops *window);
103
104    /** Set the notification and data callbacks */
105    void (*set_callbacks)(struct camera_device *,
106            camera_notify_callback notify_cb,
107            camera_data_callback data_cb,
108            camera_data_timestamp_callback data_cb_timestamp,
109            camera_request_memory get_memory,
110            void *user);
111
112    /**
113     * The following three functions all take a msg_type, which is a bitmask of
114     * the messages defined in include/ui/Camera.h
115     */
116
117    /**
118     * Enable a message, or set of messages.
119     */
120    void (*enable_msg_type)(struct camera_device *, int32_t msg_type);
121
122    /**
123     * Disable a message, or a set of messages.
124     *
125     * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera
126     * HAL should not rely on its client to call releaseRecordingFrame() to
127     * release video recording frames sent out by the cameral HAL before and
128     * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL
129     * clients must not modify/access any video recording frame after calling
130     * disableMsgType(CAMERA_MSG_VIDEO_FRAME).
131     */
132    void (*disable_msg_type)(struct camera_device *, int32_t msg_type);
133
134    /**
135     * Query whether a message, or a set of messages, is enabled.  Note that
136     * this is operates as an AND, if any of the messages queried are off, this
137     * will return false.
138     */
139    int (*msg_type_enabled)(struct camera_device *, int32_t msg_type);
140
141    /**
142     * Start preview mode.
143     */
144    int (*start_preview)(struct camera_device *);
145
146    /**
147     * Stop a previously started preview.
148     */
149    void (*stop_preview)(struct camera_device *);
150
151    /**
152     * Returns true if preview is enabled.
153     */
154    int (*preview_enabled)(struct camera_device *);
155
156    /**
157     * Request the camera HAL to store meta data or real YUV data in the video
158     * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If
159     * it is not called, the default camera HAL behavior is to store real YUV
160     * data in the video buffers.
161     *
162     * This method should be called before startRecording() in order to be
163     * effective.
164     *
165     * If meta data is stored in the video buffers, it is up to the receiver of
166     * the video buffers to interpret the contents and to find the actual frame
167     * data with the help of the meta data in the buffer. How this is done is
168     * outside of the scope of this method.
169     *
170     * Some camera HALs may not support storing meta data in the video buffers,
171     * but all camera HALs should support storing real YUV data in the video
172     * buffers. If the camera HAL does not support storing the meta data in the
173     * video buffers when it is requested to do do, INVALID_OPERATION must be
174     * returned. It is very useful for the camera HAL to pass meta data rather
175     * than the actual frame data directly to the video encoder, since the
176     * amount of the uncompressed frame data can be very large if video size is
177     * large.
178     *
179     * @param enable if true to instruct the camera HAL to store
180     *        meta data in the video buffers; false to instruct
181     *        the camera HAL to store real YUV data in the video
182     *        buffers.
183     *
184     * @return OK on success.
185     */
186    int (*store_meta_data_in_buffers)(struct camera_device *, int enable);
187
188    /**
189     * Start record mode. When a record image is available, a
190     * CAMERA_MSG_VIDEO_FRAME message is sent with the corresponding
191     * frame. Every record frame must be released by a camera HAL client via
192     * releaseRecordingFrame() before the client calls
193     * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls
194     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
195     * responsibility to manage the life-cycle of the video recording frames,
196     * and the client must not modify/access any video recording frames.
197     */
198    int (*start_recording)(struct camera_device *);
199
200    /**
201     * Stop a previously started recording.
202     */
203    void (*stop_recording)(struct camera_device *);
204
205    /**
206     * Returns true if recording is enabled.
207     */
208    int (*recording_enabled)(struct camera_device *);
209
210    /**
211     * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME.
212     *
213     * It is camera HAL client's responsibility to release video recording
214     * frames sent out by the camera HAL before the camera HAL receives a call
215     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
216     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
217     * responsibility to manage the life-cycle of the video recording frames.
218     */
219    void (*release_recording_frame)(struct camera_device *,
220                    const void *opaque);
221
222    /**
223     * Start auto focus, the notification callback routine is called with
224     * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() will be
225     * called again if another auto focus is needed.
226     */
227    int (*auto_focus)(struct camera_device *);
228
229    /**
230     * Cancels auto-focus function. If the auto-focus is still in progress,
231     * this function will cancel it. Whether the auto-focus is in progress or
232     * not, this function will return the focus position to the default.  If
233     * the camera does not support auto-focus, this is a no-op.
234     */
235    int (*cancel_auto_focus)(struct camera_device *);
236
237    /**
238     * Take a picture.
239     */
240    int (*take_picture)(struct camera_device *);
241
242    /**
243     * Cancel a picture that was started with takePicture. Calling this method
244     * when no picture is being taken is a no-op.
245     */
246    int (*cancel_picture)(struct camera_device *);
247
248    /**
249     * Set the camera parameters. This returns BAD_VALUE if any parameter is
250     * invalid or not supported.
251     */
252    int (*set_parameters)(struct camera_device *, const char *parms);
253
254    /** Retrieve the camera parameters.  The buffer returned by the camera HAL
255        must be returned back to it with put_parameters, if put_parameters
256        is not NULL.
257     */
258    char *(*get_parameters)(struct camera_device *);
259
260    /** The camera HAL uses its own memory to pass us the parameters when we
261        call get_parameters.  Use this function to return the memory back to
262        the camera HAL, if put_parameters is not NULL.  If put_parameters
263        is NULL, then you have to use free() to release the memory.
264    */
265    void (*put_parameters)(struct camera_device *, char *);
266
267    /**
268     * Send command to camera driver.
269     */
270    int (*send_command)(struct camera_device *,
271                int32_t cmd, int32_t arg1, int32_t arg2);
272
273    /**
274     * Release the hardware resources owned by this object.  Note that this is
275     * *not* done in the destructor.
276     */
277    void (*release)(struct camera_device *);
278
279    /**
280     * Dump state of the camera hardware
281     */
282    int (*dump)(struct camera_device *, int fd);
283} camera_device_ops_t;
284
285typedef struct camera_device {
286    /**
287     * camera_device.common.version must be in the range
288     * HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF). CAMERA_DEVICE_API_VERSION_1_0 is
289     * recommended.
290     */
291    hw_device_t common;
292    camera_device_ops_t *ops;
293    void *priv;
294} camera_device_t;
295
296__END_DECLS
297
298#endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */
299