Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 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 <hardware/hardware.h> |
| 28 | #include <hardware/gralloc.h> |
| 29 | |
| 30 | __BEGIN_DECLS |
| 31 | |
| 32 | /** |
| 33 | * The id of this module |
| 34 | */ |
| 35 | #define CAMERA_HARDWARE_MODULE_ID "camera" |
| 36 | |
| 37 | /** |
| 38 | * Module versioning information for the Camera hardware module, based on |
| 39 | * camera_module_t.common.module_api_version. The two most significant hex |
| 40 | * digits represent the major version, and the two least significant represent |
| 41 | * the minor version. |
| 42 | * |
| 43 | ******************************************************************************* |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 44 | * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0] |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 45 | * |
| 46 | * Camera modules that report these version numbers implement the initial |
| 47 | * camera module HAL interface. All camera devices openable through this |
| 48 | * module support only version 1 of the camera device HAL. The device_version |
| 49 | * and static_camera_characteristics fields of camera_info are not valid. Only |
| 50 | * the android.hardware.Camera API can be supported by this module and its |
| 51 | * devices. |
| 52 | * |
| 53 | ******************************************************************************* |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 54 | * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0] |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 55 | * |
| 56 | * Camera modules that report this version number implement the second version |
| 57 | * of the camera module HAL interface. Camera devices openable through this |
| 58 | * module may support either version 1.0 or version 2.0 of the camera device |
| 59 | * HAL interface. The device_version field of camera_info is always valid; the |
| 60 | * static_camera_characteristics field of camera_info is valid if the |
| 61 | * device_version field is 2.0 or higher. |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 62 | * |
| 63 | ******************************************************************************* |
| 64 | * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1] |
| 65 | * |
| 66 | * This camera module version adds support for asynchronous callbacks to the |
| 67 | * framework from the camera HAL module, which is used to notify the framework |
| 68 | * about changes to the camera module state. Modules that provide a valid |
| 69 | * set_callbacks() method must report at least this version number. |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 70 | */ |
| 71 | |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 72 | /** |
| 73 | * Predefined macros for currently-defined version numbers |
| 74 | */ |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 75 | |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 76 | /** |
| 77 | * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated |
| 78 | * as CAMERA_MODULE_API_VERSION_1_0 |
| 79 | */ |
| 80 | #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) |
| 81 | #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 82 | #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 83 | |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 84 | #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_1 |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 85 | |
| 86 | /** |
| 87 | * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated |
| 88 | * as CAMERA_DEVICE_API_VERSION_1_0 |
| 89 | */ |
| 90 | #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) |
| 91 | #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 92 | #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) |
Eino-Ville Talvala | d2a8775 | 2012-11-27 18:06:06 -0800 | [diff] [blame] | 93 | #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 94 | |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 95 | // Device version 2.x is outdated; device version 3.0 is experimental |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 96 | #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_1_0 |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 97 | |
| 98 | /** |
James Dong | d0ca70d | 2012-03-26 16:22:35 -0700 | [diff] [blame] | 99 | * Defined in /system/media/camera/include/system/camera_metadata.h |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 100 | */ |
| 101 | typedef struct camera_metadata camera_metadata_t; |
| 102 | |
Alex Ray | 9acc740 | 2013-02-07 15:44:24 -0800 | [diff] [blame] | 103 | typedef struct camera_info { |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 104 | /** |
| 105 | * The direction that the camera faces to. It should be CAMERA_FACING_BACK |
| 106 | * or CAMERA_FACING_FRONT. |
| 107 | * |
| 108 | * Version information: |
| 109 | * Valid in all camera_module versions |
| 110 | */ |
| 111 | int facing; |
| 112 | |
| 113 | /** |
| 114 | * The orientation of the camera image. The value is the angle that the |
| 115 | * camera image needs to be rotated clockwise so it shows correctly on the |
| 116 | * display in its natural orientation. It should be 0, 90, 180, or 270. |
| 117 | * |
| 118 | * For example, suppose a device has a naturally tall screen. The |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 119 | * back-facing camera sensor is mounted in landscape. You are looking at the |
| 120 | * screen. If the top side of the camera sensor is aligned with the right |
| 121 | * edge of the screen in natural orientation, the value should be 90. If the |
| 122 | * top side of a front-facing camera sensor is aligned with the right of the |
| 123 | * screen, the value should be 270. |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 124 | * |
| 125 | * Version information: |
| 126 | * Valid in all camera_module versions |
| 127 | */ |
| 128 | int orientation; |
| 129 | |
| 130 | /** |
| 131 | * The value of camera_device_t.common.version. |
| 132 | * |
| 133 | * Version information (based on camera_module_t.common.module_api_version): |
| 134 | * |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 135 | * CAMERA_MODULE_API_VERSION_1_0: |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 136 | * |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 137 | * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 138 | * not read this field. |
| 139 | * |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 140 | * CAMERA_MODULE_API_VERSION_2_0 or higher: |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 141 | * |
| 142 | * Always valid |
| 143 | * |
| 144 | */ |
| 145 | uint32_t device_version; |
| 146 | |
| 147 | /** |
| 148 | * The camera's fixed characteristics, which include all camera metadata in |
Eino-Ville Talvala | b8b6439 | 2012-08-24 12:32:17 -0700 | [diff] [blame] | 149 | * the android.*.info.* sections. This should be a sorted metadata buffer, |
| 150 | * and may not be modified or freed by the caller. The pointer should remain |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 151 | * valid for the lifetime of the camera module, and values in it may not |
| 152 | * change after it is returned by get_camera_info(). |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 153 | * |
| 154 | * Version information (based on camera_module_t.common.module_api_version): |
| 155 | * |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 156 | * CAMERA_MODULE_API_VERSION_1_0: |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 157 | * |
| 158 | * Not valid. Extra characteristics are not available. Do not read this |
| 159 | * field. |
| 160 | * |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 161 | * CAMERA_MODULE_API_VERSION_2_0 or higher: |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 162 | * |
Eino-Ville Talvala | ddc026e | 2012-03-27 16:15:25 -0700 | [diff] [blame] | 163 | * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read |
| 164 | * otherwise. |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 165 | * |
| 166 | */ |
Eino-Ville Talvala | b8b6439 | 2012-08-24 12:32:17 -0700 | [diff] [blame] | 167 | const camera_metadata_t *static_camera_characteristics; |
Alex Ray | 9acc740 | 2013-02-07 15:44:24 -0800 | [diff] [blame] | 168 | } camera_info_t; |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 169 | |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 170 | /** |
| 171 | * camera_device_status_t: |
| 172 | * |
| 173 | * The current status of the camera device, as provided by the HAL through the |
| 174 | * camera_module_callbacks.camera_device_status_change() call. |
Igor Murashkin | 152b50f | 2013-03-18 13:30:14 -0700 | [diff] [blame^] | 175 | * |
| 176 | * At module load time, the framework will assume all camera devices are in the |
| 177 | * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke |
| 178 | * camera_module_callbacks::camera_device_status_change to inform the framework |
| 179 | * of any initially NOT_PRESENT devices. |
| 180 | * |
| 181 | * Allowed transitions: |
| 182 | * PRESENT -> NOT_PRESENT |
| 183 | * NOT_PRESENT -> ENUMERATING |
| 184 | * NOT_PRESENT -> PRESENT |
| 185 | * ENUMERATING -> PRESENT |
| 186 | * ENUMERATING -> NOT_PRESENT |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 187 | */ |
| 188 | typedef enum camera_device_status { |
| 189 | /** |
| 190 | * The camera device is not currently connected, and opening it will return |
| 191 | * failure. Calls to get_camera_info must still succeed, and provide the |
| 192 | * same information it would if the camera were connected |
| 193 | */ |
| 194 | CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, |
| 195 | |
| 196 | /** |
| 197 | * The camera device is connected, and opening it will succeed. The |
| 198 | * information returned by get_camera_info cannot change due to this status |
| 199 | * change. By default, the framework will assume all devices are in this |
| 200 | * state. |
| 201 | */ |
Igor Murashkin | 152b50f | 2013-03-18 13:30:14 -0700 | [diff] [blame^] | 202 | CAMERA_DEVICE_STATUS_PRESENT = 1, |
| 203 | |
| 204 | /** |
| 205 | * The camera device is connected, but it is undergoing an enumeration and |
| 206 | * so opening the device will return -EBUSY. Calls to get_camera_info |
| 207 | * must still succeed, as if the camera was in the PRESENT status. |
| 208 | */ |
| 209 | CAMERA_DEVICE_STATUS_ENUMERATING = 2, |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 210 | |
| 211 | } camera_device_status_t; |
| 212 | |
| 213 | /** |
| 214 | * Callback functions for the camera HAL module to use to inform the framework |
| 215 | * of changes to the camera subsystem. These are called only by HAL modules |
| 216 | * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL |
| 217 | * module API interface. |
| 218 | */ |
| 219 | typedef struct camera_module_callbacks { |
| 220 | |
| 221 | /** |
| 222 | * camera_device_status_change: |
| 223 | * |
| 224 | * Callback to the framework to indicate that the state of a specific camera |
| 225 | * device has changed. At module load time, the framework will assume all |
| 226 | * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL |
| 227 | * must call this method to inform the framework of any initially |
| 228 | * NOT_PRESENT devices. |
| 229 | * |
| 230 | * camera_module_callbacks: The instance of camera_module_callbacks_t passed |
| 231 | * to the module with set_callbacks. |
| 232 | * |
| 233 | * camera_id: The ID of the camera device that has a new status. |
| 234 | * |
| 235 | * new_status: The new status code, one of the camera_device_status_t enums, |
| 236 | * or a platform-specific status. |
| 237 | * |
| 238 | */ |
| 239 | void (*camera_device_status_change)(const struct camera_module_callbacks*, |
| 240 | int camera_id, |
| 241 | int new_status); |
| 242 | |
| 243 | } camera_module_callbacks_t; |
| 244 | |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 245 | typedef struct camera_module { |
| 246 | hw_module_t common; |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 247 | |
| 248 | /** |
| 249 | * get_number_of_cameras: |
| 250 | * |
| 251 | * Returns the number of camera devices accessible through the camera |
| 252 | * module. The camera devices are numbered 0 through N-1, where N is the |
| 253 | * value returned by this call. The name of the camera device for open() is |
| 254 | * simply the number converted to a string. That is, "0" for camera ID 0, |
| 255 | * "1" for camera ID 1. |
| 256 | * |
| 257 | * The value here must be static, and cannot change after the first call to |
| 258 | * this method |
| 259 | */ |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 260 | int (*get_number_of_cameras)(void); |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 261 | |
| 262 | /** |
| 263 | * get_camera_info: |
| 264 | * |
| 265 | * Return the static camera information for a given camera device. This |
| 266 | * information may not change for a camera device. |
| 267 | * |
| 268 | */ |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 269 | int (*get_camera_info)(int camera_id, struct camera_info *info); |
Eino-Ville Talvala | d76f8af | 2013-02-13 15:29:48 -0800 | [diff] [blame] | 270 | |
| 271 | /** |
| 272 | * set_callbacks: |
| 273 | * |
| 274 | * Provide callback function pointers to the HAL module to inform framework |
| 275 | * of asynchronous camera module events. The framework will call this |
| 276 | * function once after initial camera HAL module load, after the |
| 277 | * get_number_of_cameras() method is called for the first time, and before |
| 278 | * any other calls to the module. |
| 279 | * |
| 280 | * Version information (based on camera_module_t.common.module_api_version): |
| 281 | * |
| 282 | * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0: |
| 283 | * |
| 284 | * Not provided by HAL module. Framework may not call this function. |
| 285 | * |
| 286 | * CAMERA_MODULE_API_VERSION_2_1: |
| 287 | * |
| 288 | * Valid to be called by the framework. |
| 289 | * |
| 290 | */ |
| 291 | int (*set_callbacks)(const camera_module_callbacks_t *callbacks); |
| 292 | |
Eino-Ville Talvala | 8bf364e | 2011-12-22 13:50:37 -0800 | [diff] [blame] | 293 | } camera_module_t; |
| 294 | |
| 295 | __END_DECLS |
| 296 | |
| 297 | #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */ |