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