Imported Upstream version 4.2.2-2
[deb_android-headers.git] / hardware / camera.h
CommitLineData
1e494cf4
JB
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#ifdef HTC_3D_SUPPORT
79 int (*set_3d_mode)(const struct preview_stream_ops *w, int r1, int r2, int r3);
80#endif
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 */