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 <stdbool.h>
24 #include <sys/cdefs.h>
25 #include <sys/types.h>
26 #include <cutils/native_handle.h>
27 #include <system/camera.h>
28 #include <system/camera_vendor_tags.h>
29 #include <hardware/hardware.h>
30 #include <hardware/gralloc.h>
31 
32 __BEGIN_DECLS
33 
34 /**
35  * The id of this module
36  */
37 #define CAMERA_HARDWARE_MODULE_ID "camera"
38 
39 /**
40  * Module versioning information for the Camera hardware module, based on
41  * camera_module_t.common.module_api_version. The two most significant hex
42  * digits represent the major version, and the two least significant represent
43  * the minor version.
44  *
45  *******************************************************************************
46  * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0]
47  *
48  * Camera modules that report these version numbers implement the initial
49  * camera module HAL interface. All camera devices openable through this
50  * module support only version 1 of the camera device HAL. The device_version
51  * and static_camera_characteristics fields of camera_info are not valid. Only
52  * the android.hardware.Camera API can be supported by this module and its
53  * devices.
54  *
55  *******************************************************************************
56  * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0]
57  *
58  * Camera modules that report this version number implement the second version
59  * of the camera module HAL interface. Camera devices openable through this
60  * module may support either version 1.0 or version 2.0 of the camera device
61  * HAL interface. The device_version field of camera_info is always valid; the
62  * static_camera_characteristics field of camera_info is valid if the
63  * device_version field is 2.0 or higher.
64  *
65  *******************************************************************************
66  * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1]
67  *
68  * This camera module version adds support for asynchronous callbacks to the
69  * framework from the camera HAL module, which is used to notify the framework
70  * about changes to the camera module state. Modules that provide a valid
71  * set_callbacks() method must report at least this version number.
72  *
73  *******************************************************************************
74  * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2]
75  *
76  * This camera module version adds vendor tag support from the module, and
77  * deprecates the old vendor_tag_query_ops that were previously only
78  * accessible with a device open.
79  *
80  *******************************************************************************
81  * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3]
82  *
83  * This camera module version adds open legacy camera HAL device support.
84  * Framework can use it to open the camera device as lower device HAL version
85  * HAL device if the same device can support multiple device API versions.
86  * The standard hardware module open call (common.methods->open) continues
87  * to open the camera device with the latest supported version, which is
88  * also the version listed in camera_info_t.device_version.
89  *
90  *******************************************************************************
91  * Version: 2.4 [CAMERA_MODULE_API_VERSION_2_4]
92  *
93  * This camera module version adds below API changes:
94  *
95  * 1. Torch mode support. The framework can use it to turn on torch mode for
96  * any camera device that has a flash unit, without opening a camera device. The
97  * camera device has a higher priority accessing the flash unit than the camera
98  * module; opening a camera device will turn off the torch if it had been enabled
99  * through the module interface. When there are any resource conflicts, such as
100  * open() is called to open a camera device, the camera HAL module must notify the
101  * framework through the torch mode status callback that the torch mode has been
102  * turned off.
103  *
104  * 2. External camera (e.g. USB hot-plug camera) support. The API updates specify that
105  * the camera static info is only available when camera is connected and ready to
106  * use for external hot-plug cameras. Calls to get static info will be invalid
107  * calls when camera status is not CAMERA_DEVICE_STATUS_PRESENT. The frameworks
108  * will only count on device status change callbacks to manage the available external
109  * camera list.
110  *
111  * 3. Camera arbitration hints. This module version adds support for explicitly
112  * indicating the number of camera devices that can be simultaneously opened and used.
113  * To specify valid combinations of devices, the resource_cost and conflicting_devices
114  * fields should always be set in the camera_info structure returned by the
115  * get_camera_info call.
116  *
117  * 4. Module initialization method. This will be called by the camera service
118  * right after the HAL module is loaded, to allow for one-time initialization
119  * of the HAL. It is called before any other module methods are invoked.
120  */
121 
122 /**
123  * Predefined macros for currently-defined version numbers
124  */
125 
126 /**
127  * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated
128  * as CAMERA_MODULE_API_VERSION_1_0
129  */
130 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
131 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
132 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1)
133 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2)
134 #define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3)
135 #define CAMERA_MODULE_API_VERSION_2_4 HARDWARE_MODULE_API_VERSION(2, 4)
136 
137 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_4
138 
139 /**
140  * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated
141  * as CAMERA_DEVICE_API_VERSION_1_0
142  */
143 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
144 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0)
145 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1)
146 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0)
147 #define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1)
148 #define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2)
149 #define CAMERA_DEVICE_API_VERSION_3_3 HARDWARE_DEVICE_API_VERSION(3, 3)
150 
151 // Device version 3.3 is current, older HAL camera device versions are not
152 // recommended for new devices.
153 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_3
154 
155 /**
156  * Defined in /system/media/camera/include/system/camera_metadata.h
157  */
158 typedef struct camera_metadata camera_metadata_t;
159 
160 typedef struct camera_info {
161  /**
162  * The direction that the camera faces to. See system/core/include/system/camera.h
163  * for camera facing definitions.
164  *
165  * Version information (based on camera_module_t.common.module_api_version):
166  *
167  * CAMERA_MODULE_API_VERSION_2_3 or lower:
168  *
169  * It should be CAMERA_FACING_BACK or CAMERA_FACING_FRONT.
170  *
171  * CAMERA_MODULE_API_VERSION_2_4 or higher:
172  *
173  * It should be CAMERA_FACING_BACK, CAMERA_FACING_FRONT or
174  * CAMERA_FACING_EXTERNAL.
175  */
176  int facing;
177 
178  /**
179  * The orientation of the camera image. The value is the angle that the
180  * camera image needs to be rotated clockwise so it shows correctly on the
181  * display in its natural orientation. It should be 0, 90, 180, or 270.
182  *
183  * For example, suppose a device has a naturally tall screen. The
184  * back-facing camera sensor is mounted in landscape. You are looking at the
185  * screen. If the top side of the camera sensor is aligned with the right
186  * edge of the screen in natural orientation, the value should be 90. If the
187  * top side of a front-facing camera sensor is aligned with the right of the
188  * screen, the value should be 270.
189  *
190  * Version information (based on camera_module_t.common.module_api_version):
191  *
192  * CAMERA_MODULE_API_VERSION_2_3 or lower:
193  *
194  * Valid in all camera_module versions.
195  *
196  * CAMERA_MODULE_API_VERSION_2_4 or higher:
197  *
198  * Valid if camera facing is CAMERA_FACING_BACK or CAMERA_FACING_FRONT,
199  * not valid if camera facing is CAMERA_FACING_EXTERNAL.
200  */
202 
203  /**
204  * The value of camera_device_t.common.version.
205  *
206  * Version information (based on camera_module_t.common.module_api_version):
207  *
208  * CAMERA_MODULE_API_VERSION_1_0:
209  *
210  * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do
211  * not read this field.
212  *
213  * CAMERA_MODULE_API_VERSION_2_0 or higher:
214  *
215  * Always valid
216  *
217  */
218  uint32_t device_version;
219 
220  /**
221  * The camera's fixed characteristics, which include all static camera metadata
222  * specified in system/media/camera/docs/docs.html. This should be a sorted metadata
223  * buffer, and may not be modified or freed by the caller. The pointer should remain
224  * valid for the lifetime of the camera module, and values in it may not
225  * change after it is returned by get_camera_info().
226  *
227  * Version information (based on camera_module_t.common.module_api_version):
228  *
229  * CAMERA_MODULE_API_VERSION_1_0:
230  *
231  * Not valid. Extra characteristics are not available. Do not read this
232  * field.
233  *
234  * CAMERA_MODULE_API_VERSION_2_0 or higher:
235  *
236  * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read
237  * otherwise.
238  *
239  */
241 
242  /**
243  * The total resource "cost" of using this camera, represented as an integer
244  * value in the range [0, 100] where 100 represents total usage of the shared
245  * resource that is the limiting bottleneck of the camera subsystem. This may
246  * be a very rough estimate, and is used as a hint to the camera service to
247  * determine when to disallow multiple applications from simultaneously
248  * opening different cameras advertised by the camera service.
249  *
250  * The camera service must be able to simultaneously open and use any
251  * combination of camera devices exposed by the HAL where the sum of
252  * the resource costs of these cameras is <= 100. For determining cost,
253  * each camera device must be assumed to be configured and operating at
254  * the maximally resource-consuming framerate and stream size settings
255  * available in the configuration settings exposed for that device through
256  * the camera metadata.
257  *
258  * The camera service may still attempt to simultaneously open combinations
259  * of camera devices with a total resource cost > 100. This may succeed or
260  * fail. If this succeeds, combinations of configurations that are not
261  * supported due to resource constraints from having multiple open devices
262  * should fail during the configure calls. If the total resource cost is
263  * <= 100, open and configure should never fail for any stream configuration
264  * settings or other device capabilities that would normally succeed for a
265  * device when it is the only open camera device.
266  *
267  * This field will be used to determine whether background applications are
268  * allowed to use this camera device while other applications are using other
269  * camera devices. Note: multiple applications will never be allowed by the
270  * camera service to simultaneously open the same camera device.
271  *
272  * Example use cases:
273  *
274  * Ex. 1: Camera Device 0 = Back Camera
275  * Camera Device 1 = Front Camera
276  * - Using both camera devices causes a large framerate slowdown due to
277  * limited ISP bandwidth.
278  *
279  * Configuration:
280  *
281  * Camera Device 0 - resource_cost = 51
282  * conflicting_devices = null
283  * Camera Device 1 - resource_cost = 51
284  * conflicting_devices = null
285  *
286  * Result:
287  *
288  * Since the sum of the resource costs is > 100, if a higher-priority
289  * application has either device open, no lower-priority applications will be
290  * allowed by the camera service to open either device. If a lower-priority
291  * application is using a device that a higher-priority subsequently attempts
292  * to open, the lower-priority application will be forced to disconnect the
293  * the device.
294  *
295  * If the highest-priority application chooses, it may still attempt to open
296  * both devices (since these devices are not listed as conflicting in the
297  * conflicting_devices fields), but usage of these devices may fail in the
298  * open or configure calls.
299  *
300  * Ex. 2: Camera Device 0 = Left Back Camera
301  * Camera Device 1 = Right Back Camera
302  * Camera Device 2 = Combined stereo camera using both right and left
303  * back camera sensors used by devices 0, and 1
304  * Camera Device 3 = Front Camera
305  * - Due to do hardware constraints, up to two cameras may be open at once. The
306  * combined stereo camera may never be used at the same time as either of the
307  * two back camera devices (device 0, 1), and typically requires too much
308  * bandwidth to use at the same time as the front camera (device 3).
309  *
310  * Configuration:
311  *
312  * Camera Device 0 - resource_cost = 50
313  * conflicting_devices = { 2 }
314  * Camera Device 1 - resource_cost = 50
315  * conflicting_devices = { 2 }
316  * Camera Device 2 - resource_cost = 100
317  * conflicting_devices = { 0, 1 }
318  * Camera Device 3 - resource_cost = 50
319  * conflicting_devices = null
320  *
321  * Result:
322  *
323  * Based on the conflicting_devices fields, the camera service guarantees that
324  * the following sets of open devices will never be allowed: { 1, 2 }, { 0, 2 }.
325  *
326  * Based on the resource_cost fields, if a high-priority foreground application
327  * is using camera device 0, a background application would be allowed to open
328  * camera device 1 or 3 (but would be forced to disconnect it again if the
329  * foreground application opened another device).
330  *
331  * The highest priority application may still attempt to simultaneously open
332  * devices 0, 2, and 3, but the HAL may fail in open or configure calls for
333  * this combination.
334  *
335  * Ex. 3: Camera Device 0 = Back Camera
336  * Camera Device 1 = Front Camera
337  * Camera Device 2 = Low-power Front Camera that uses the same
338  * sensor as device 1, but only exposes image stream
339  * resolutions that can be used in low-power mode
340  * - Using both front cameras (device 1, 2) at the same time is impossible due
341  * a shared physical sensor. Using the back and "high-power" front camera
342  * (device 1) may be impossible for some stream configurations due to hardware
343  * limitations, but the "low-power" front camera option may always be used as
344  * it has special dedicated hardware.
345  *
346  * Configuration:
347  *
348  * Camera Device 0 - resource_cost = 100
349  * conflicting_devices = null
350  * Camera Device 1 - resource_cost = 100
351  * conflicting_devices = { 2 }
352  * Camera Device 2 - resource_cost = 0
353  * conflicting_devices = { 1 }
354  * Result:
355  *
356  * Based on the conflicting_devices fields, the camera service guarantees that
357  * the following sets of open devices will never be allowed: { 1, 2 }.
358  *
359  * Based on the resource_cost fields, only the highest priority application
360  * may attempt to open both device 0 and 1 at the same time. If a higher-priority
361  * application is not using device 1 or 2, a low-priority background application
362  * may open device 2 (but will be forced to disconnect it if a higher-priority
363  * application subsequently opens device 1 or 2).
364  *
365  * Version information (based on camera_module_t.common.module_api_version):
366  *
367  * CAMERA_MODULE_API_VERSION_2_3 or lower:
368  *
369  * Not valid. Can be assumed to be 100. Do not read this field.
370  *
371  * CAMERA_MODULE_API_VERSION_2_4 or higher:
372  *
373  * Always valid.
374  */
376 
377  /**
378  * An array of camera device IDs represented as NULL-terminated strings
379  * indicating other devices that cannot be simultaneously opened while this
380  * camera device is in use.
381  *
382  * This field is intended to be used to indicate that this camera device
383  * is a composite of several other camera devices, or otherwise has
384  * hardware dependencies that prohibit simultaneous usage. If there are no
385  * dependencies, a NULL may be returned in this field to indicate this.
386  *
387  * The camera service will never simultaneously open any of the devices
388  * in this list while this camera device is open.
389  *
390  * The strings pointed to in this field will not be cleaned up by the camera
391  * service, and must remain while this device is plugged in.
392  *
393  * Version information (based on camera_module_t.common.module_api_version):
394  *
395  * CAMERA_MODULE_API_VERSION_2_3 or lower:
396  *
397  * Not valid. Can be assumed to be NULL. Do not read this field.
398  *
399  * CAMERA_MODULE_API_VERSION_2_4 or higher:
400  *
401  * Always valid.
402  */
404 
405  /**
406  * The length of the array given in the conflicting_devices field.
407  *
408  * Version information (based on camera_module_t.common.module_api_version):
409  *
410  * CAMERA_MODULE_API_VERSION_2_3 or lower:
411  *
412  * Not valid. Can be assumed to be 0. Do not read this field.
413  *
414  * CAMERA_MODULE_API_VERSION_2_4 or higher:
415  *
416  * Always valid.
417  */
419 
420 } camera_info_t;
421 
422 /**
423  * camera_device_status_t:
424  *
425  * The current status of the camera device, as provided by the HAL through the
426  * camera_module_callbacks.camera_device_status_change() call.
427  *
428  * At module load time, the framework will assume all camera devices are in the
429  * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke
430  * camera_module_callbacks::camera_device_status_change to inform the framework
431  * of any initially NOT_PRESENT devices.
432  *
433  * Allowed transitions:
434  * PRESENT -> NOT_PRESENT
435  * NOT_PRESENT -> ENUMERATING
436  * NOT_PRESENT -> PRESENT
437  * ENUMERATING -> PRESENT
438  * ENUMERATING -> NOT_PRESENT
439  */
440 typedef enum camera_device_status {
441  /**
442  * The camera device is not currently connected, and opening it will return
443  * failure.
444  *
445  * Version information (based on camera_module_t.common.module_api_version):
446  *
447  * CAMERA_MODULE_API_VERSION_2_3 or lower:
448  *
449  * Calls to get_camera_info must still succeed, and provide the same information
450  * it would if the camera were connected.
451  *
452  * CAMERA_MODULE_API_VERSION_2_4:
453  *
454  * The camera device at this status must return -EINVAL for get_camera_info call,
455  * as the device is not connected.
456  */
458 
459  /**
460  * The camera device is connected, and opening it will succeed.
461  *
462  * CAMERA_MODULE_API_VERSION_2_3 or lower:
463  *
464  * The information returned by get_camera_info cannot change due to this status
465  * change. By default, the framework will assume all devices are in this state.
466  *
467  * CAMERA_MODULE_API_VERSION_2_4:
468  *
469  * The information returned by get_camera_info will become valid after a device's
470  * status changes to this. By default, the framework will assume all devices are in
471  * this state.
472  */
474 
475  /**
476  * The camera device is connected, but it is undergoing an enumeration and
477  * so opening the device will return -EBUSY.
478  *
479  * CAMERA_MODULE_API_VERSION_2_3 or lower:
480  *
481  * Calls to get_camera_info must still succeed, as if the camera was in the
482  * PRESENT status.
483  *
484  * CAMERA_MODULE_API_VERSION_2_4:
485  *
486  * The camera device at this status must return -EINVAL for get_camera_info for call,
487  * as the device is not ready.
488  */
490 
492 
493 /**
494  * torch_mode_status_t:
495  *
496  * The current status of the torch mode, as provided by the HAL through the
497  * camera_module_callbacks.torch_mode_status_change() call.
498  *
499  * The torch mode status of a camera device is applicable only when the camera
500  * device is present. The framework will not call set_torch_mode() to turn on
501  * torch mode of a camera device if the camera device is not present. At module
502  * load time, the framework will assume torch modes are in the
503  * TORCH_MODE_STATUS_AVAILABLE_OFF state if the camera device is present and
504  * android.flash.info.available is reported as true via get_camera_info() call.
505  *
506  * The behaviors of the camera HAL module that the framework expects in the
507  * following situations when a camera device's status changes:
508  * 1. A previously-disconnected camera device becomes connected.
509  * After camera_module_callbacks::camera_device_status_change() is invoked
510  * to inform the framework that the camera device is present, the framework
511  * will assume the camera device's torch mode is in
512  * TORCH_MODE_STATUS_AVAILABLE_OFF state. The camera HAL module does not need
513  * to invoke camera_module_callbacks::torch_mode_status_change() unless the
514  * flash unit is unavailable to use by set_torch_mode().
515  *
516  * 2. A previously-connected camera becomes disconnected.
517  * After camera_module_callbacks::camera_device_status_change() is invoked
518  * to inform the framework that the camera device is not present, the
519  * framework will not call set_torch_mode() for the disconnected camera
520  * device until its flash unit becomes available again. The camera HAL
521  * module does not need to invoke
522  * camera_module_callbacks::torch_mode_status_change() separately to inform
523  * that the flash unit has become unavailable.
524  *
525  * 3. open() is called to open a camera device.
526  * The camera HAL module must invoke
527  * camera_module_callbacks::torch_mode_status_change() for all flash units
528  * that have entered TORCH_MODE_STATUS_NOT_AVAILABLE state and can not be
529  * turned on by calling set_torch_mode() anymore due to this open() call.
530  * open() must not trigger TORCH_MODE_STATUS_AVAILABLE_OFF before
531  * TORCH_MODE_STATUS_NOT_AVAILABLE for all flash units that have become
532  * unavailable.
533  *
534  * 4. close() is called to close a camera device.
535  * The camera HAL module must invoke
536  * camera_module_callbacks::torch_mode_status_change() for all flash units
537  * that have entered TORCH_MODE_STATUS_AVAILABLE_OFF state and can be turned
538  * on by calling set_torch_mode() again because of enough resources freed
539  * up by this close() call.
540  *
541  * Note that the framework calling set_torch_mode() successfully must trigger
542  * TORCH_MODE_STATUS_AVAILABLE_OFF or TORCH_MODE_STATUS_AVAILABLE_ON callback
543  * for the given camera device. Additionally it must trigger
544  * TORCH_MODE_STATUS_AVAILABLE_OFF callbacks for other previously-on torch
545  * modes if HAL cannot keep multiple torch modes on simultaneously.
546  */
547 typedef enum torch_mode_status {
548 
549  /**
550  * The flash unit is no longer available and the torch mode can not be
551  * turned on by calling set_torch_mode(). If the torch mode is on, it
552  * will be turned off by HAL before HAL calls torch_mode_status_change().
553  */
555 
556  /**
557  * A torch mode has become off and available to be turned on via
558  * set_torch_mode(). This may happen in the following
559  * cases:
560  * 1. After the resources to turn on the torch mode have become available.
561  * 2. After set_torch_mode() is called to turn off the torch mode.
562  * 3. After the framework turned on the torch mode of some other camera
563  * device and HAL had to turn off the torch modes of any camera devices
564  * that were previously on.
565  */
567 
568  /**
569  * A torch mode has become on and available to be turned off via
570  * set_torch_mode(). This can happen only after set_torch_mode() is called
571  * to turn on the torch mode.
572  */
574 
576 
577 /**
578  * Callback functions for the camera HAL module to use to inform the framework
579  * of changes to the camera subsystem.
580  *
581  * Version information (based on camera_module_t.common.module_api_version):
582  *
583  * Each callback is called only by HAL modules implementing the indicated
584  * version or higher of the HAL module API interface.
585  *
586  * CAMERA_MODULE_API_VERSION_2_1:
587  * camera_device_status_change()
588  *
589  * CAMERA_MODULE_API_VERSION_2_4:
590  * torch_mode_status_change()
591 
592  */
593 typedef struct camera_module_callbacks {
594 
595  /**
596  * camera_device_status_change:
597  *
598  * Callback to the framework to indicate that the state of a specific camera
599  * device has changed. At module load time, the framework will assume all
600  * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL
601  * must call this method to inform the framework of any initially
602  * NOT_PRESENT devices.
603  *
604  * This callback is added for CAMERA_MODULE_API_VERSION_2_1.
605  *
606  * camera_module_callbacks: The instance of camera_module_callbacks_t passed
607  * to the module with set_callbacks.
608  *
609  * camera_id: The ID of the camera device that has a new status.
610  *
611  * new_status: The new status code, one of the camera_device_status_t enums,
612  * or a platform-specific status.
613  *
614  */
616  int camera_id,
617  int new_status);
618 
619  /**
620  * torch_mode_status_change:
621  *
622  * Callback to the framework to indicate that the state of the torch mode
623  * of the flash unit associated with a specific camera device has changed.
624  * At module load time, the framework will assume the torch modes are in
625  * the TORCH_MODE_STATUS_AVAILABLE_OFF state if android.flash.info.available
626  * is reported as true via get_camera_info() call.
627  *
628  * This callback is added for CAMERA_MODULE_API_VERSION_2_4.
629  *
630  * camera_module_callbacks: The instance of camera_module_callbacks_t
631  * passed to the module with set_callbacks.
632  *
633  * camera_id: The ID of camera device whose flash unit has a new torch mode
634  * status.
635  *
636  * new_status: The new status code, one of the torch_mode_status_t enums.
637  */
639  const char* camera_id,
640  int new_status);
641 
642 
644 
645 typedef struct camera_module {
646  /**
647  * Common methods of the camera module. This *must* be the first member of
648  * camera_module as users of this structure will cast a hw_module_t to
649  * camera_module pointer in contexts where it's known the hw_module_t
650  * references a camera_module.
651  *
652  * The return values for common.methods->open for camera_module are:
653  *
654  * 0: On a successful open of the camera device.
655  *
656  * -ENODEV: The camera device cannot be opened due to an internal
657  * error.
658  *
659  * -EINVAL: The input arguments are invalid, i.e. the id is invalid,
660  * and/or the module is invalid.
661  *
662  * -EBUSY: The camera device was already opened for this camera id
663  * (by using this method or open_legacy),
664  * regardless of the device HAL version it was opened as.
665  *
666  * -EUSERS: The maximal number of camera devices that can be
667  * opened concurrently were opened already, either by
668  * this method or the open_legacy method.
669  *
670  * All other return values from common.methods->open will be treated as
671  * -ENODEV.
672  */
674 
675  /**
676  * get_number_of_cameras:
677  *
678  * Returns the number of camera devices accessible through the camera
679  * module. The camera devices are numbered 0 through N-1, where N is the
680  * value returned by this call. The name of the camera device for open() is
681  * simply the number converted to a string. That is, "0" for camera ID 0,
682  * "1" for camera ID 1.
683  *
684  * Version information (based on camera_module_t.common.module_api_version):
685  *
686  * CAMERA_MODULE_API_VERSION_2_3 or lower:
687  *
688  * The value here must be static, and cannot change after the first call
689  * to this method.
690  *
691  * CAMERA_MODULE_API_VERSION_2_4 or higher:
692  *
693  * The value here must be static, and must count only built-in cameras,
694  * which have CAMERA_FACING_BACK or CAMERA_FACING_FRONT camera facing values
695  * (camera_info.facing). The HAL must not include the external cameras
696  * (camera_info.facing == CAMERA_FACING_EXTERNAL) into the return value
697  * of this call. Frameworks will use camera_device_status_change callback
698  * to manage number of external cameras.
699  */
700  int (*get_number_of_cameras)(void);
701 
702  /**
703  * get_camera_info:
704  *
705  * Return the static camera information for a given camera device. This
706  * information may not change for a camera device.
707  *
708  * Return values:
709  *
710  * 0: On a successful operation
711  *
712  * -ENODEV: The information cannot be provided due to an internal
713  * error.
714  *
715  * -EINVAL: The input arguments are invalid, i.e. the id is invalid,
716  * and/or the module is invalid.
717  *
718  * Version information (based on camera_module_t.common.module_api_version):
719  *
720  * CAMERA_MODULE_API_VERSION_2_4 or higher:
721  *
722  * When a camera is disconnected, its camera id becomes invalid. Calling this
723  * this method with this invalid camera id will get -EINVAL and NULL camera
724  * static metadata (camera_info.static_camera_characteristics).
725  */
726  int (*get_camera_info)(int camera_id, struct camera_info *info);
727 
728  /**
729  * set_callbacks:
730  *
731  * Provide callback function pointers to the HAL module to inform framework
732  * of asynchronous camera module events. The framework will call this
733  * function once after initial camera HAL module load, after the
734  * get_number_of_cameras() method is called for the first time, and before
735  * any other calls to the module.
736  *
737  * Version information (based on camera_module_t.common.module_api_version):
738  *
739  * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0:
740  *
741  * Not provided by HAL module. Framework may not call this function.
742  *
743  * CAMERA_MODULE_API_VERSION_2_1:
744  *
745  * Valid to be called by the framework.
746  *
747  * Return values:
748  *
749  * 0: On a successful operation
750  *
751  * -ENODEV: The operation cannot be completed due to an internal
752  * error.
753  *
754  * -EINVAL: The input arguments are invalid, i.e. the callbacks are
755  * null
756  */
757  int (*set_callbacks)(const camera_module_callbacks_t *callbacks);
758 
759  /**
760  * get_vendor_tag_ops:
761  *
762  * Get methods to query for vendor extension metadata tag information. The
763  * HAL should fill in all the vendor tag operation methods, or leave ops
764  * unchanged if no vendor tags are defined.
765  *
766  * The vendor_tag_ops structure used here is defined in:
767  * system/media/camera/include/system/vendor_tags.h
768  *
769  * Version information (based on camera_module_t.common.module_api_version):
770  *
771  * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1:
772  * Not provided by HAL module. Framework may not call this function.
773  *
774  * CAMERA_MODULE_API_VERSION_2_2:
775  * Valid to be called by the framework.
776  */
777  void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops);
778 
779  /**
780  * open_legacy:
781  *
782  * Open a specific legacy camera HAL device if multiple device HAL API
783  * versions are supported by this camera HAL module. For example, if the
784  * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and
785  * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id,
786  * framework can call this function to open the camera device as
787  * CAMERA_DEVICE_API_VERSION_1_0 device.
788  *
789  * This is an optional method. A Camera HAL module does not need to support
790  * more than one device HAL version per device, and such modules may return
791  * -ENOSYS for all calls to this method. For all older HAL device API
792  * versions that are not supported, it may return -EOPNOTSUPP. When above
793  * cases occur, The normal open() method (common.methods->open) will be
794  * used by the framework instead.
795  *
796  * Version information (based on camera_module_t.common.module_api_version):
797  *
798  * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2:
799  * Not provided by HAL module. Framework will not call this function.
800  *
801  * CAMERA_MODULE_API_VERSION_2_3:
802  * Valid to be called by the framework.
803  *
804  * Return values:
805  *
806  * 0: On a successful open of the camera device.
807  *
808  * -ENOSYS This method is not supported.
809  *
810  * -EOPNOTSUPP: The requested HAL version is not supported by this method.
811  *
812  * -EINVAL: The input arguments are invalid, i.e. the id is invalid,
813  * and/or the module is invalid.
814  *
815  * -EBUSY: The camera device was already opened for this camera id
816  * (by using this method or common.methods->open method),
817  * regardless of the device HAL version it was opened as.
818  *
819  * -EUSERS: The maximal number of camera devices that can be
820  * opened concurrently were opened already, either by
821  * this method or common.methods->open method.
822  */
823  int (*open_legacy)(const struct hw_module_t* module, const char* id,
824  uint32_t halVersion, struct hw_device_t** device);
825 
826  /**
827  * set_torch_mode:
828  *
829  * Turn on or off the torch mode of the flash unit associated with a given
830  * camera ID. If the operation is successful, HAL must notify the framework
831  * torch state by invoking
832  * camera_module_callbacks.torch_mode_status_change() with the new state.
833  *
834  * The camera device has a higher priority accessing the flash unit. When
835  * there are any resource conflicts, such as open() is called to open a
836  * camera device, HAL module must notify the framework through
837  * camera_module_callbacks.torch_mode_status_change() that the
838  * torch mode has been turned off and the torch mode state has become
839  * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode
840  * become available again, HAL module must notify the framework through
841  * camera_module_callbacks.torch_mode_status_change() that the torch mode
842  * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to
843  * be called.
844  *
845  * When the framework calls set_torch_mode() to turn on the torch mode of a
846  * flash unit, if HAL cannot keep multiple torch modes on simultaneously,
847  * HAL should turn off the torch mode that was turned on by
848  * a previous set_torch_mode() call and notify the framework that the torch
849  * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF.
850  *
851  * Version information (based on camera_module_t.common.module_api_version):
852  *
853  * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3:
854  * Not provided by HAL module. Framework will not call this function.
855  *
856  * CAMERA_MODULE_API_VERSION_2_4:
857  * Valid to be called by the framework.
858  *
859  * Return values:
860  *
861  * 0: On a successful operation.
862  *
863  * -ENOSYS: The camera device does not support this operation. It is
864  * returned if and only if android.flash.info.available is
865  * false.
866  *
867  * -EBUSY: The camera device is already in use.
868  *
869  * -EUSERS: The resources needed to turn on the torch mode are not
870  * available, typically because other camera devices are
871  * holding the resources to make using the flash unit not
872  * possible.
873  *
874  * -EINVAL: camera_id is invalid.
875  *
876  */
877  int (*set_torch_mode)(const char* camera_id, bool enabled);
878 
879  /**
880  * init:
881  *
882  * This method is called by the camera service before any other methods
883  * are invoked, right after the camera HAL library has been successfully
884  * loaded. It may be left as NULL by the HAL module, if no initialization
885  * in needed.
886  *
887  * It can be used by HAL implementations to perform initialization and
888  * other one-time operations.
889  *
890  * Version information (based on camera_module_t.common.module_api_version):
891  *
892  * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3:
893  * Not provided by HAL module. Framework will not call this function.
894  *
895  * CAMERA_MODULE_API_VERSION_2_4:
896  * If not NULL, will always be called by the framework once after the HAL
897  * module is loaded, before any other HAL module method is called.
898  *
899  * Return values:
900  *
901  * 0: On a successful operation.
902  *
903  * -ENODEV: Initialization cannot be completed due to an internal
904  * error. The HAL must be assumed to be in a nonfunctional
905  * state.
906  *
907  */
908  int (*init)();
909 
910  /* reserved for future use */
911  void* reserved[5];
913 
914 __END_DECLS
915 
916 #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
void * reserved[5]
char ** conflicting_devices
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)
enum torch_mode_status torch_mode_status_t
int(* set_torch_mode)(const char *camera_id, bool enabled)
torch_mode_status
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)
void(* torch_mode_status_change)(const struct camera_module_callbacks *, const char *camera_id, int new_status)
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)
size_t conflicting_devices_length