Android Hardware Abstraction Layer
camera.h
Go to the documentation of this file.
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 
41 struct camera_memory;
42 typedef void (*camera_release_memory)(struct camera_memory *mem);
43 
44 typedef struct camera_memory {
45  void *data;
46  size_t size;
47  void *handle;
50 
51 typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs,
52  void *user);
53 
54 typedef void (*camera_notify_callback)(int32_t msg_type,
55  int32_t ext1,
56  int32_t ext2,
57  void *user);
58 
59 typedef 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 
63 typedef 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 
70 typedef struct preview_stream_ops {
72  buffer_handle_t** buffer, int *stride);
74  buffer_handle_t* buffer);
76  buffer_handle_t* buffer);
77  int (*set_buffer_count)(struct preview_stream_ops* w, int count);
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);
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);
94 
95 struct camera_device;
96 typedef struct camera_device_ops {
97  /** Set the ANativeWindow to which preview frames are sent */
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  */
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  */
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  */
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);
281 
282 typedef 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  */
290  void *priv;
292 
293 __END_DECLS
294 
295 #endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */