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