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 ******************************************************************************* 44 * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0] 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 ******************************************************************************* 54 * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0] 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. 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. 70 * 71 ******************************************************************************* 72 * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2] 73 * 74 * This camera module version adds vendor tag support from the module, and 75 * deprecates the old vendor_tag_query_ops that were previously only 76 * accessible with a device open. 77 */ 78 79 /** 80 * Predefined macros for currently-defined version numbers 81 */ 82 83 /** 84 * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated 85 * as CAMERA_MODULE_API_VERSION_1_0 86 */ 87 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 88 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) 89 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) 90 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2) 91 92 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_2 93 94 /** 95 * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated 96 * as CAMERA_DEVICE_API_VERSION_1_0 97 */ 98 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) 99 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) 100 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) 101 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) 102 #define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1) 103 104 // Device version 2.x is outdated; device version 3.0 is experimental 105 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_1_0 106 107 /** 108 * Defined in /system/media/camera/include/system/camera_metadata.h 109 */ 110 typedef struct camera_metadata camera_metadata_t; 111 112 typedef struct camera_info { 113 /** 114 * The direction that the camera faces to. It should be CAMERA_FACING_BACK 115 * or CAMERA_FACING_FRONT. 116 * 117 * Version information: 118 * Valid in all camera_module versions 119 */ 120 int facing; 121 122 /** 123 * The orientation of the camera image. The value is the angle that the 124 * camera image needs to be rotated clockwise so it shows correctly on the 125 * display in its natural orientation. It should be 0, 90, 180, or 270. 126 * 127 * For example, suppose a device has a naturally tall screen. The 128 * back-facing camera sensor is mounted in landscape. You are looking at the 129 * screen. If the top side of the camera sensor is aligned with the right 130 * edge of the screen in natural orientation, the value should be 90. If the 131 * top side of a front-facing camera sensor is aligned with the right of the 132 * screen, the value should be 270. 133 * 134 * Version information: 135 * Valid in all camera_module versions 136 */ 137 int orientation; 138 139 /** 140 * The value of camera_device_t.common.version. 141 * 142 * Version information (based on camera_module_t.common.module_api_version): 143 * 144 * CAMERA_MODULE_API_VERSION_1_0: 145 * 146 * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do 147 * not read this field. 148 * 149 * CAMERA_MODULE_API_VERSION_2_0 or higher: 150 * 151 * Always valid 152 * 153 */ 154 uint32_t device_version; 155 156 /** 157 * The camera's fixed characteristics, which include all camera metadata in 158 * the android.*.info.* sections. This should be a sorted metadata buffer, 159 * and may not be modified or freed by the caller. The pointer should remain 160 * valid for the lifetime of the camera module, and values in it may not 161 * change after it is returned by get_camera_info(). 162 * 163 * Version information (based on camera_module_t.common.module_api_version): 164 * 165 * CAMERA_MODULE_API_VERSION_1_0: 166 * 167 * Not valid. Extra characteristics are not available. Do not read this 168 * field. 169 * 170 * CAMERA_MODULE_API_VERSION_2_0 or higher: 171 * 172 * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read 173 * otherwise. 174 * 175 */ 176 const camera_metadata_t *static_camera_characteristics; 177 } camera_info_t; 178 179 /** 180 * camera_device_status_t: 181 * 182 * The current status of the camera device, as provided by the HAL through the 183 * camera_module_callbacks.camera_device_status_change() call. 184 * 185 * At module load time, the framework will assume all camera devices are in the 186 * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke 187 * camera_module_callbacks::camera_device_status_change to inform the framework 188 * of any initially NOT_PRESENT devices. 189 * 190 * Allowed transitions: 191 * PRESENT -> NOT_PRESENT 192 * NOT_PRESENT -> ENUMERATING 193 * NOT_PRESENT -> PRESENT 194 * ENUMERATING -> PRESENT 195 * ENUMERATING -> NOT_PRESENT 196 */ 197 typedef enum camera_device_status { 198 /** 199 * The camera device is not currently connected, and opening it will return 200 * failure. Calls to get_camera_info must still succeed, and provide the 201 * same information it would if the camera were connected 202 */ 203 CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, 204 205 /** 206 * The camera device is connected, and opening it will succeed. The 207 * information returned by get_camera_info cannot change due to this status 208 * change. By default, the framework will assume all devices are in this 209 * state. 210 */ 211 CAMERA_DEVICE_STATUS_PRESENT = 1, 212 213 /** 214 * The camera device is connected, but it is undergoing an enumeration and 215 * so opening the device will return -EBUSY. Calls to get_camera_info 216 * must still succeed, as if the camera was in the PRESENT status. 217 */ 218 CAMERA_DEVICE_STATUS_ENUMERATING = 2, 219 220 } camera_device_status_t; 221 222 /** 223 * Callback functions for the camera HAL module to use to inform the framework 224 * of changes to the camera subsystem. These are called only by HAL modules 225 * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL 226 * module API interface. 227 */ 228 typedef struct camera_module_callbacks { 229 230 /** 231 * camera_device_status_change: 232 * 233 * Callback to the framework to indicate that the state of a specific camera 234 * device has changed. At module load time, the framework will assume all 235 * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL 236 * must call this method to inform the framework of any initially 237 * NOT_PRESENT devices. 238 * 239 * camera_module_callbacks: The instance of camera_module_callbacks_t passed 240 * to the module with set_callbacks. 241 * 242 * camera_id: The ID of the camera device that has a new status. 243 * 244 * new_status: The new status code, one of the camera_device_status_t enums, 245 * or a platform-specific status. 246 * 247 */ 248 void (*camera_device_status_change)(const struct camera_module_callbacks*, 249 int camera_id, 250 int new_status); 251 252 } camera_module_callbacks_t; 253 254 /** 255 * Set up vendor-specific tag query methods. These are needed to properly query 256 * entries with vendor-specified tags, potentially returned by get_camera_info. 257 * 258 * This should be used in place of vendor_tag_query_ops, which are deprecated. 259 */ 260 typedef struct vendor_tag_ops vendor_tag_ops_t; 261 struct vendor_tag_ops { 262 /** 263 * Get the number of vendor tags supported on this platform. Used to 264 * calculate the size of buffer needed for holding the array of all tags 265 * returned by get_all_tags(). 266 */ 267 int (*get_tag_count)(const vendor_tag_ops_t *v); 268 269 /** 270 * Fill an array with all the supported vendor tags on this platform. 271 * get_tag_count() returns the number of tags supported, and 272 * tag_array will be allocated with enough space to hold all of the tags. 273 */ 274 void (*get_all_tags)(const vendor_tag_ops_t *v, uint32_t *tag_array); 275 276 /** 277 * Get vendor section name for a vendor-specified entry tag. Only called for 278 * vendor-defined tags. The section name must start with the name of the 279 * vendor in the Java package style. For example, CameraZoom Inc. must 280 * prefix their sections with "com.camerazoom." Must return NULL if the tag 281 * is outside the bounds of vendor-defined sections. 282 * 283 * There may be different vendor-defined tag sections, for example the 284 * phone maker, the chipset maker, and the camera module maker may each 285 * have their own "com.vendor."-prefixed section. 286 * 287 * The memory pointed to by the return value must remain valid for the 288 * lifetime that the module is loaded, and is owned by the module. 289 */ 290 const char *(*get_section_name)(const vendor_tag_ops_t *v, uint32_t tag); 291 292 /** 293 * Get tag name for a vendor-specified entry tag. Only called for 294 * vendor-defined tags. Must return NULL if the it is not a vendor-defined 295 * tag. 296 * 297 * The memory pointed to by the return value must remain valid for the 298 * lifetime that the module is loaded, and is owned by the module. 299 */ 300 const char *(*get_tag_name)(const vendor_tag_ops_t *v, uint32_t tag); 301 302 /** 303 * Get tag type for a vendor-specified entry tag. Only called for tags >= 304 * 0x80000000. Must return -1 if the tag is outside the bounds of 305 * vendor-defined sections. 306 */ 307 int (*get_tag_type)(const vendor_tag_ops_t *v, uint32_t tag); 308 309 /* reserved for future use */ 310 void* reserved[8]; 311 }; 312 313 typedef struct camera_module { 314 hw_module_t common; 315 316 /** 317 * get_number_of_cameras: 318 * 319 * Returns the number of camera devices accessible through the camera 320 * module. The camera devices are numbered 0 through N-1, where N is the 321 * value returned by this call. The name of the camera device for open() is 322 * simply the number converted to a string. That is, "0" for camera ID 0, 323 * "1" for camera ID 1. 324 * 325 * The value here must be static, and cannot change after the first call to 326 * this method 327 */ 328 int (*get_number_of_cameras)(void); 329 330 /** 331 * get_camera_info: 332 * 333 * Return the static camera information for a given camera device. This 334 * information may not change for a camera device. 335 * 336 */ 337 int (*get_camera_info)(int camera_id, struct camera_info *info); 338 339 /** 340 * set_callbacks: 341 * 342 * Provide callback function pointers to the HAL module to inform framework 343 * of asynchronous camera module events. The framework will call this 344 * function once after initial camera HAL module load, after the 345 * get_number_of_cameras() method is called for the first time, and before 346 * any other calls to the module. 347 * 348 * Version information (based on camera_module_t.common.module_api_version): 349 * 350 * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0: 351 * 352 * Not provided by HAL module. Framework may not call this function. 353 * 354 * CAMERA_MODULE_API_VERSION_2_1: 355 * 356 * Valid to be called by the framework. 357 * 358 */ 359 int (*set_callbacks)(const camera_module_callbacks_t *callbacks); 360 361 /** 362 * get_vendor_tag_ops: 363 * 364 * Get methods to query for vendor extension metadata tag information. The 365 * HAL should fill in all the vendor tag operation methods, or leave ops 366 * unchanged if no vendor tags are defined. 367 * 368 * Version information (based on camera_module_t.common.module_api_version): 369 * 370 * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1: 371 * Not provided by HAL module. Framework may not call this function. 372 * 373 * CAMERA_MODULE_API_VERSION_2_2: 374 * Valid to be called by the framework. 375 */ 376 void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops); 377 378 /* reserved for future use */ 379 void* reserved[8]; 380 } camera_module_t; 381 382 __END_DECLS 383 384 #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */ 385