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  * 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 
44 struct camera_memory;
45 typedef void (*camera_release_memory)(struct camera_memory *mem);
46 
47 typedef struct camera_memory {
48  void *data;
49  size_t size;
50  void *handle;
53 
54 typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs,
55  void *user);
56 
57 typedef void (*camera_notify_callback)(int32_t msg_type,
58  int32_t ext1,
59  int32_t ext2,
60  void *user);
61 
62 typedef 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 
66 typedef 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 
73 typedef struct preview_stream_ops {
75  buffer_handle_t** buffer, int *stride);
77  buffer_handle_t* buffer);
79  buffer_handle_t* buffer);
80  int (*set_buffer_count)(struct preview_stream_ops* w, int count);
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);
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);
97 
98 struct camera_device;
99 typedef struct camera_device_ops {
100  /** Set the ANativeWindow to which preview frames are sent */
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  */
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  */
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  */
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);
284 
285 typedef 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  */
293  void *priv;
295 
296 __END_DECLS
297 
298 #endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */
void(* camera_data_callback)(int32_t msg_type, const camera_memory_t *data, unsigned int index, camera_frame_metadata_t *metadata, void *user)
Definition: camera.h:62
void(* set_callbacks)(struct camera_device *, camera_notify_callback notify_cb, camera_data_callback data_cb, camera_data_timestamp_callback data_cb_timestamp, camera_request_memory get_memory, void *user)
Definition: camera.h:105
void(* camera_data_timestamp_callback)(int64_t timestamp, int32_t msg_type, const camera_memory_t *data, unsigned int index, void *user)
Definition: camera.h:66
void * priv
Definition: camera.h:293
struct preview_stream_ops preview_stream_ops_t
void * data
Definition: camera.h:48
struct camera_memory camera_memory_t
void(* release_recording_frame)(struct camera_device *, const void *opaque)
Definition: camera.h:219
void(* disable_msg_type)(struct camera_device *, int32_t msg_type)
Definition: camera.h:132
int(* dequeue_buffer)(struct preview_stream_ops *w, buffer_handle_t **buffer, int *stride)
Definition: camera.h:74
int(* set_buffers_geometry)(struct preview_stream_ops *pw, int w, int h, int format)
Definition: camera.h:81
int(* preview_enabled)(struct camera_device *)
Definition: camera.h:154
size_t size
Definition: camera.h:49
int(* enqueue_buffer)(struct preview_stream_ops *w, buffer_handle_t *buffer)
Definition: camera.h:76
int(* cancel_auto_focus)(struct camera_device *)
Definition: camera.h:235
void(* stop_preview)(struct camera_device *)
Definition: camera.h:149
void(* release)(struct camera_device *)
Definition: camera.h:277
camera_device_ops_t * ops
Definition: camera.h:292
int(* store_meta_data_in_buffers)(struct camera_device *, int enable)
Definition: camera.h:186
int(* set_crop)(struct preview_stream_ops *w, int left, int top, int right, int bottom)
Definition: camera.h:83
struct camera_device camera_device_t
void(* put_parameters)(struct camera_device *, char *)
Definition: camera.h:265
int(* set_timestamp)(struct preview_stream_ops *w, int64_t timestamp)
Definition: camera.h:95
void(* camera_release_memory)(struct camera_memory *mem)
Definition: camera.h:45
int(* set_swap_interval)(struct preview_stream_ops *w, int interval)
Definition: camera.h:86
camera_release_memory release
Definition: camera.h:51
int(* get_min_undequeued_buffer_count)(const struct preview_stream_ops *w, int *count)
Definition: camera.h:87
int(* set_buffer_count)(struct preview_stream_ops *w, int count)
Definition: camera.h:80
int(* set_preview_window)(struct camera_device *, struct preview_stream_ops *window)
Definition: camera.h:101
int(* send_command)(struct camera_device *, int32_t cmd, int32_t arg1, int32_t arg2)
Definition: camera.h:270
int(* cancel_picture)(struct camera_device *)
Definition: camera.h:246
void * handle
Definition: camera.h:50
int(* take_picture)(struct camera_device *)
Definition: camera.h:240
camera_memory_t *(* camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs, void *user)
Definition: camera.h:54
void(* stop_recording)(struct camera_device *)
Definition: camera.h:203
int(* cancel_buffer)(struct preview_stream_ops *w, buffer_handle_t *buffer)
Definition: camera.h:78
void(* camera_notify_callback)(int32_t msg_type, int32_t ext1, int32_t ext2, void *user)
Definition: camera.h:57
int(* lock_buffer)(struct preview_stream_ops *w, buffer_handle_t *buffer)
Definition: camera.h:89
int(* dump)(struct camera_device *, int fd)
Definition: camera.h:282
int(* start_recording)(struct camera_device *)
Definition: camera.h:198
int(* msg_type_enabled)(struct camera_device *, int32_t msg_type)
Definition: camera.h:139
void(* enable_msg_type)(struct camera_device *, int32_t msg_type)
Definition: camera.h:120
int(* start_preview)(struct camera_device *)
Definition: camera.h:144
int(* auto_focus)(struct camera_device *)
Definition: camera.h:227
int(* set_usage)(struct preview_stream_ops *w, int usage)
Definition: camera.h:85
hw_device_t common
Definition: camera.h:291
struct camera_device_ops camera_device_ops_t
int(* recording_enabled)(struct camera_device *)
Definition: camera.h:208
int(* set_parameters)(struct camera_device *, const char *parms)
Definition: camera.h:252