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 /** 73 * Predefined macros for currently-defined version numbers 74 */ 75 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) 82 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) 83 84 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_1 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) 92 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) 93 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) 94 95 // Device version 2.x is outdated; device version 3.0 is experimental 96 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_1_0 97 98 /** 99 * Defined in /system/media/camera/include/system/camera_metadata.h 100 */ 101 typedef struct camera_metadata camera_metadata_t; 102 103 typedef struct camera_info { 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 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. 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 * 135 * CAMERA_MODULE_API_VERSION_1_0: 136 * 137 * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do 138 * not read this field. 139 * 140 * CAMERA_MODULE_API_VERSION_2_0 or higher: 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 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 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(). 153 * 154 * Version information (based on camera_module_t.common.module_api_version): 155 * 156 * CAMERA_MODULE_API_VERSION_1_0: 157 * 158 * Not valid. Extra characteristics are not available. Do not read this 159 * field. 160 * 161 * CAMERA_MODULE_API_VERSION_2_0 or higher: 162 * 163 * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read 164 * otherwise. 165 * 166 */ 167 const camera_metadata_t *static_camera_characteristics; 168 } camera_info_t; 169 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. 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 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 */ 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, 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 245 typedef struct camera_module { 246 hw_module_t common; 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 */ 260 int (*get_number_of_cameras)(void); 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 */ 269 int (*get_camera_info)(int camera_id, struct camera_info *info); 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 293 } camera_module_t; 294 295 __END_DECLS 296 297 #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */ 298
