camera_common.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2012 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 // FIXME: add well-defined names for cameras
18 
19 #ifndef ANDROID_INCLUDE_CAMERA_COMMON_H
20 #define ANDROID_INCLUDE_CAMERA_COMMON_H
21 
22 #include <stdint.h>
23 #include <sys/cdefs.h>
24 #include <sys/types.h>
25 #include <cutils/native_handle.h>
26 #include <system/camera.h>
27 #include <system/camera_vendor_tags.h>
28 #include <hardware/hardware.h>
29 #include <hardware/gralloc.h>
30 
31 __BEGIN_DECLS
32 
33 /**
34  * The id of this module
35  */
36 #define CAMERA_HARDWARE_MODULE_ID "camera"
37 
38 /**
39  * Module versioning information for the Camera hardware module, based on
40  * camera_module_t.common.module_api_version. The two most significant hex
41  * digits represent the major version, and the two least significant represent
42  * the minor version.
43  *
44  *******************************************************************************
45  * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0]
46  *
47  * Camera modules that report these version numbers implement the initial
48  * camera module HAL interface. All camera devices openable through this
49  * module support only version 1 of the camera device HAL. The device_version
50  * and static_camera_characteristics fields of camera_info are not valid. Only
51  * the android.hardware.Camera API can be supported by this module and its
52  * devices.
53  *
54  *******************************************************************************
55  * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0]
56  *
57  * Camera modules that report this version number implement the second version
58  * of the camera module HAL interface. Camera devices openable through this
59  * module may support either version 1.0 or version 2.0 of the camera device
60  * HAL interface. The device_version field of camera_info is always valid; the
61  * static_camera_characteristics field of camera_info is valid if the
62  * device_version field is 2.0 or higher.
63  *
64  *******************************************************************************
65  * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1]
66  *
67  * This camera module version adds support for asynchronous callbacks to the
68  * framework from the camera HAL module, which is used to notify the framework
69  * about changes to the camera module state. Modules that provide a valid
70  * set_callbacks() method must report at least this version number.
71  *
72  *******************************************************************************
73  * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2]
74  *
75  * This camera module version adds vendor tag support from the module, and
76  * deprecates the old vendor_tag_query_ops that were previously only
77  * accessible with a device open.
78  *
79  *******************************************************************************
80  * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3]
81  *
82  * This camera module version adds open legacy camera HAL device support.
83  * Framework can use it to open the camera device as lower device HAL version
84  * HAL device if the same device can support multiple device API versions.
85  * The standard hardware module open call (common.methods->open) continues
86  * to open the camera device with the latest supported version, which is
87  * also the version listed in camera_info_t.device_version.
88  */
89 
90 /**
91  * Predefined macros for currently-defined version numbers
92  */
93 
94 /**
95  * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated
96  * as CAMERA_MODULE_API_VERSION_1_0
97  */
98 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
99 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
100 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1)
101 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2)
102 #define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3)
103 
104 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_3
105 
106 /**
107  * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated
108  * as CAMERA_DEVICE_API_VERSION_1_0
109  */
110 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
111 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0)
112 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1)
113 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0)
114 #define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1)
115 #define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2)
116 
117 // Device version 3.2 is current, older HAL camera device versions are not
118 // recommended for new devices.
119 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_2
120 
121 /**
122  * Defined in /system/media/camera/include/system/camera_metadata.h
123  */
124 typedef struct camera_metadata camera_metadata_t;
125 
126 typedef struct camera_info {
127  /**
128  * The direction that the camera faces to. It should be CAMERA_FACING_BACK
129  * or CAMERA_FACING_FRONT.
130  *
131  * Version information:
132  * Valid in all camera_module versions
133  */
134  int facing;
135 
136  /**
137  * The orientation of the camera image. The value is the angle that the
138  * camera image needs to be rotated clockwise so it shows correctly on the
139  * display in its natural orientation. It should be 0, 90, 180, or 270.
140  *
141  * For example, suppose a device has a naturally tall screen. The
142  * back-facing camera sensor is mounted in landscape. You are looking at the
143  * screen. If the top side of the camera sensor is aligned with the right
144  * edge of the screen in natural orientation, the value should be 90. If the
145  * top side of a front-facing camera sensor is aligned with the right of the
146  * screen, the value should be 270.
147  *
148  * Version information:
149  * Valid in all camera_module versions
150  */
152 
153  /**
154  * The value of camera_device_t.common.version.
155  *
156  * Version information (based on camera_module_t.common.module_api_version):
157  *
158  * CAMERA_MODULE_API_VERSION_1_0:
159  *
160  * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do
161  * not read this field.
162  *
163  * CAMERA_MODULE_API_VERSION_2_0 or higher:
164  *
165  * Always valid
166  *
167  */
168  uint32_t device_version;
169 
170  /**
171  * The camera's fixed characteristics, which include all camera metadata in
172  * the android.*.info.* sections. This should be a sorted metadata buffer,
173  * and may not be modified or freed by the caller. The pointer should remain
174  * valid for the lifetime of the camera module, and values in it may not
175  * change after it is returned by get_camera_info().
176  *
177  * Version information (based on camera_module_t.common.module_api_version):
178  *
179  * CAMERA_MODULE_API_VERSION_1_0:
180  *
181  * Not valid. Extra characteristics are not available. Do not read this
182  * field.
183  *
184  * CAMERA_MODULE_API_VERSION_2_0 or higher:
185  *
186  * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read
187  * otherwise.
188  *
189  */
191 } camera_info_t;
192 
193 /**
194  * camera_device_status_t:
195  *
196  * The current status of the camera device, as provided by the HAL through the
197  * camera_module_callbacks.camera_device_status_change() call.
198  *
199  * At module load time, the framework will assume all camera devices are in the
200  * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke
201  * camera_module_callbacks::camera_device_status_change to inform the framework
202  * of any initially NOT_PRESENT devices.
203  *
204  * Allowed transitions:
205  * PRESENT -> NOT_PRESENT
206  * NOT_PRESENT -> ENUMERATING
207  * NOT_PRESENT -> PRESENT
208  * ENUMERATING -> PRESENT
209  * ENUMERATING -> NOT_PRESENT
210  */
211 typedef enum camera_device_status {
212  /**
213  * The camera device is not currently connected, and opening it will return
214  * failure. Calls to get_camera_info must still succeed, and provide the
215  * same information it would if the camera were connected
216  */
218 
219  /**
220  * The camera device is connected, and opening it will succeed. The
221  * information returned by get_camera_info cannot change due to this status
222  * change. By default, the framework will assume all devices are in this
223  * state.
224  */
226 
227  /**
228  * The camera device is connected, but it is undergoing an enumeration and
229  * so opening the device will return -EBUSY. Calls to get_camera_info
230  * must still succeed, as if the camera was in the PRESENT status.
231  */
233 
235 
236 /**
237  * Callback functions for the camera HAL module to use to inform the framework
238  * of changes to the camera subsystem. These are called only by HAL modules
239  * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL
240  * module API interface.
241  */
242 typedef struct camera_module_callbacks {
243 
244  /**
245  * camera_device_status_change:
246  *
247  * Callback to the framework to indicate that the state of a specific camera
248  * device has changed. At module load time, the framework will assume all
249  * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL
250  * must call this method to inform the framework of any initially
251  * NOT_PRESENT devices.
252  *
253  * camera_module_callbacks: The instance of camera_module_callbacks_t passed
254  * to the module with set_callbacks.
255  *
256  * camera_id: The ID of the camera device that has a new status.
257  *
258  * new_status: The new status code, one of the camera_device_status_t enums,
259  * or a platform-specific status.
260  *
261  */
263  int camera_id,
264  int new_status);
265 
267 
268 typedef struct camera_module {
269  /**
270  * Common methods of the camera module. This *must* be the first member of
271  * camera_module as users of this structure will cast a hw_module_t to
272  * camera_module pointer in contexts where it's known the hw_module_t
273  * references a camera_module.
274  *
275  * The return values for common.methods->open for camera_module are:
276  *
277  * 0: On a successful open of the camera device.
278  *
279  * -ENODEV: The camera device cannot be opened due to an internal
280  * error.
281  *
282  * -EINVAL: The input arguments are invalid, i.e. the id is invalid,
283  * and/or the module is invalid.
284  *
285  * -EBUSY: The camera device was already opened for this camera id
286  * (by using this method or open_legacy),
287  * regardless of the device HAL version it was opened as.
288  *
289  * -EUSERS: The maximal number of camera devices that can be
290  * opened concurrently were opened already, either by
291  * this method or the open_legacy method.
292  *
293  * All other return values from common.methods->open will be treated as
294  * -ENODEV.
295  */
297 
298  /**
299  * get_number_of_cameras:
300  *
301  * Returns the number of camera devices accessible through the camera
302  * module. The camera devices are numbered 0 through N-1, where N is the
303  * value returned by this call. The name of the camera device for open() is
304  * simply the number converted to a string. That is, "0" for camera ID 0,
305  * "1" for camera ID 1.
306  *
307  * The value here must be static, and cannot change after the first call to
308  * this method
309  */
310  int (*get_number_of_cameras)(void);
311 
312  /**
313  * get_camera_info:
314  *
315  * Return the static camera information for a given camera device. This
316  * information may not change for a camera device.
317  *
318  * Return values:
319  *
320  * 0: On a successful operation
321  *
322  * -ENODEV: The information cannot be provided due to an internal
323  * error.
324  *
325  * -EINVAL: The input arguments are invalid, i.e. the id is invalid,
326  * and/or the module is invalid.
327  */
328  int (*get_camera_info)(int camera_id, struct camera_info *info);
329 
330  /**
331  * set_callbacks:
332  *
333  * Provide callback function pointers to the HAL module to inform framework
334  * of asynchronous camera module events. The framework will call this
335  * function once after initial camera HAL module load, after the
336  * get_number_of_cameras() method is called for the first time, and before
337  * any other calls to the module.
338  *
339  * Version information (based on camera_module_t.common.module_api_version):
340  *
341  * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0:
342  *
343  * Not provided by HAL module. Framework may not call this function.
344  *
345  * CAMERA_MODULE_API_VERSION_2_1:
346  *
347  * Valid to be called by the framework.
348  *
349  * Return values:
350  *
351  * 0: On a successful operation
352  *
353  * -ENODEV: The operation cannot be completed due to an internal
354  * error.
355  *
356  * -EINVAL: The input arguments are invalid, i.e. the callbacks are
357  * null
358  */
359  int (*set_callbacks)(const camera_module_callbacks_t *callbacks);
360 
361  /**
362  * get_vendor_tag_ops:
363  *
364  * Get methods to query for vendor extension metadata tag information. The
365  * HAL should fill in all the vendor tag operation methods, or leave ops
366  * unchanged if no vendor tags are defined.
367  *
368  * The vendor_tag_ops structure used here is defined in:
369  * system/media/camera/include/system/vendor_tags.h
370  *
371  * Version information (based on camera_module_t.common.module_api_version):
372  *
373  * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1:
374  * Not provided by HAL module. Framework may not call this function.
375  *
376  * CAMERA_MODULE_API_VERSION_2_2:
377  * Valid to be called by the framework.
378  */
379  void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops);
380 
381  /**
382  * open_legacy:
383  *
384  * Open a specific legacy camera HAL device if multiple device HAL API
385  * versions are supported by this camera HAL module. For example, if the
386  * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and
387  * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id,
388  * framework can call this function to open the camera device as
389  * CAMERA_DEVICE_API_VERSION_1_0 device.
390  *
391  * This is an optional method. A Camera HAL module does not need to support
392  * more than one device HAL version per device, and such modules may return
393  * -ENOSYS for all calls to this method. For all older HAL device API
394  * versions that are not supported, it may return -EOPNOTSUPP. When above
395  * cases occur, The normal open() method (common.methods->open) will be
396  * used by the framework instead.
397  *
398  * Version information (based on camera_module_t.common.module_api_version):
399  *
400  * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2:
401  * Not provided by HAL module. Framework will not call this function.
402  *
403  * CAMERA_MODULE_API_VERSION_2_3:
404  * Valid to be called by the framework.
405  *
406  * Return values:
407  *
408  * 0: On a successful open of the camera device.
409  *
410  * -ENOSYS This method is not supported.
411  *
412  * -EOPNOTSUPP: The requested HAL version is not supported by this method.
413  *
414  * -EINVAL: The input arguments are invalid, i.e. the id is invalid,
415  * and/or the module is invalid.
416  *
417  * -EBUSY: The camera device was already opened for this camera id
418  * (by using this method or common.methods->open method),
419  * regardless of the device HAL version it was opened as.
420  *
421  * -EUSERS: The maximal number of camera devices that can be
422  * opened concurrently were opened already, either by
423  * this method or common.methods->open method.
424  */
425  int (*open_legacy)(const struct hw_module_t* module, const char* id,
426  uint32_t halVersion, struct hw_device_t** device);
427 
428  /* reserved for future use */
429  void* reserved[7];
431 
432 __END_DECLS
433 
434 #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */
struct camera_metadata camera_metadata_t
enum camera_device_status camera_device_status_t
const char * id
Definition: hardware.h:133
struct camera_module_callbacks camera_module_callbacks_t
uint32_t device_version
void(* camera_device_status_change)(const struct camera_module_callbacks *, int camera_id, int new_status)
hw_module_t common
const camera_metadata_t * static_camera_characteristics
int(* get_camera_info)(int camera_id, struct camera_info *info)
void * reserved[7]
camera_device_status
struct camera_module camera_module_t
void(* get_vendor_tag_ops)(vendor_tag_ops_t *ops)
int(* set_callbacks)(const camera_module_callbacks_t *callbacks)
int(* get_number_of_cameras)(void)
struct camera_info camera_info_t
int(* open_legacy)(const struct hw_module_t *module, const char *id, uint32_t halVersion, struct hw_device_t **device)