1/* 2 * Copyright (C) 2016 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 17package android.hardware.camera.common@1.0; 18 19/** 20 * Common enumeration and structure definitions for all HALs under 21 * android.hardware.camera 22 */ 23 24/** 25 * Status codes for camera HAL method calls. 26 * 27 */ 28enum Status : uint32_t { 29 /** 30 * Method call succeeded 31 */ 32 OK = 0, 33 34 /** 35 * One of the arguments to the method call is invalid. For example, 36 * the camera ID is unknown. 37 */ 38 ILLEGAL_ARGUMENT = 1, 39 40 /** 41 * The specified camera device is already in use 42 */ 43 CAMERA_IN_USE = 2, 44 45 /** 46 * The HAL cannot support more simultaneous cameras in use. 47 */ 48 MAX_CAMERAS_IN_USE = 3, 49 50 /** 51 * This HAL does not support this method. 52 */ 53 METHOD_NOT_SUPPORTED = 4, 54 55 /** 56 * The specified camera device does not support this operation. 57 */ 58 OPERATION_NOT_SUPPORTED = 5, 59 60 /** 61 * This camera device is no longer connected or otherwise available for use 62 */ 63 CAMERA_DISCONNECTED = 6, 64 65 /** 66 * The HAL has encountered an internal error and cannot complete the 67 * request. 68 */ 69 INTERNAL_ERROR = 7 70}; 71 72/** 73 * Possible states that the flash unit on a closed camera device can be set to 74 * via the ICameraProvider::setTorchMode() method. 75 */ 76enum TorchMode : uint32_t { 77 OFF = 0, // Turn off the flash 78 ON = 1 // Turn on the flash to torch mode 79}; 80 81/** 82 * Camera metadata type - duplicated from VNDK libcamera_metadata for vendor tag 83 * definitions. 84 */ 85enum CameraMetadataType : uint32_t { 86 // Unsigned 8-bit integer (uint8_t) 87 BYTE = 0, 88 // Signed 32-bit integer (int32_t) 89 INT32 = 1, 90 // 32-bit float (float) 91 FLOAT = 2, 92 // Signed 64-bit integer (int64_t) 93 INT64 = 3, 94 // 64-bit float (double) 95 DOUBLE = 4, 96 // A 64-bit fraction (camera_metadata_rational_t) 97 RATIONAL = 5 98}; 99 100/** 101 * A single vendor-unique metadata tag. 102 * The full name of the tag is <sectionName>.<tagName> 103 */ 104struct VendorTag { 105 uint32_t tagId; // Tag identifier, must be >= TagBoundaryId::VENDOR 106 string tagName; // Name of tag, not including section name 107 CameraMetadataType tagType; 108}; 109 110/** 111 * A set of related vendor tags. 112 */ 113struct VendorTagSection { 114 string sectionName; // Section name; must be namespaced within vendor's name 115 vec<VendorTag> tags; // List of tags in this section 116}; 117 118enum TagBoundaryId : uint32_t { 119 AOSP = 0x0, // First valid tag id for android-defined tags 120 VENDOR = 0x80000000u // First valid tag id for vendor extension tags 121}; 122 123/** 124 * CameraDeviceStatus 125 * 126 * The current status of a camera device, as sent by a camera provider HAL 127 * through the ICameraProviderCallback::cameraDeviceStatusChange() call. 128 * 129 * At startup, the camera service must assume all internal camera devices listed 130 * by ICameraProvider::getCameraIdList() are in the PRESENT state. The provider 131 * must invoke ICameraProviderCallback::cameraDeviceStatusChange to inform the 132 * service of any initially NOT_PRESENT internal devices, and of any PRESENT 133 * external camera devices, as soon as the camera service has called 134 * ICameraProvider::setCallback(). 135 * 136 * Allowed state transitions: 137 * PRESENT -> NOT_PRESENT 138 * NOT_PRESENT -> ENUMERATING 139 * NOT_PRESENT -> PRESENT 140 * ENUMERATING -> PRESENT 141 * ENUMERATING -> NOT_PRESENT 142 */ 143enum CameraDeviceStatus : uint32_t { 144 /** 145 * The camera device is not currently connected, and trying to reference it 146 * in provider method calls must return status code ILLEGAL_ARGUMENT. 147 * 148 */ 149 NOT_PRESENT = 0, 150 151 /** 152 * The camera device is connected, and opening it is possible, as long as 153 * sufficient resources are available. 154 * 155 * By default, the framework must assume all devices returned by 156 * ICameraProvider::getCameraIdList() are in this state. 157 */ 158 PRESENT = 1, 159 160 /** 161 * The camera device is connected, but it is undergoing enumeration and 162 * startup, and so opening the device must return CAMERA_IN_USE. 163 * 164 * Attempting to call ICameraProvider::getCameraCharacteristics() must 165 * succeed, however. 166 */ 167 ENUMERATING = 2, 168 169}; 170 171/** 172 * TorchModeStatus: 173 * 174 * The current status of the torch mode on a given camera device, sent by a 175 * camera provider HAL via the ICameraProviderCallback::TorchModeStatusChange() 176 * call. 177 * 178 * The torch mode status of a camera device is applicable only when the camera 179 * device is present. The camera service must not call 180 * ICameraProvider::setTorchMode() to turn on torch mode of a camera device if 181 * the camera device is not present. At camera service startup time, the 182 * framework must assume torch modes are in the AVAILABLE_OFF state if the 183 * camera device is present and the camera characteristics entry 184 * android.flash.info.available is reported as true via 185 * ICameraProvider::getCameraCharacteristics() call. The same is assumed for 186 * external camera devices when they are initially connected. 187 * 188 * The camera service requires the following behaviors from the camera provider 189 * HAL when a camera device's status changes: 190 * 191 * 1. A previously-disconnected camera device becomes connected. After 192 * ICameraProviderCallback::CameraDeviceStatusChange() is invoked to inform 193 * the camera service that the camera device is present, the framework must 194 * assume the camera device's torch mode is in AVAILABLE_OFF state if it 195 * has a flash unit. The camera provider HAL does not need to invoke 196 * ICameraProviderCallback::TorchModeStatusChange() unless the flash unit 197 * is unavailable to use by ICameraProvider::setTorchMode(). 198 * 199 * 2. A previously-connected camera becomes disconnected. After 200 * ICameraProviderCallback::CameraDeviceStatusChange() is invoked to inform 201 * the camera service that the camera device is not present, the framework 202 * must not call ICameraProvider::setTorchMode() for the disconnected camera 203 * device until it is connected again. The camera provider HAL does not 204 * need to invoke ICameraProviderCallback::TorchModeStatusChange() 205 * separately to inform that the flash unit has become NOT_AVAILABLE. 206 * 207 * 3. openCameraDevice() or openCameraDeviceVersion() is called to open a 208 * camera device. The camera provider HAL must invoke 209 * ICameraProviderCallback::TorchModeStatusChange() for all flash units 210 * that have entered NOT_AVAILABLE state and can not be turned on by 211 * calling ICameraProvider::setTorchMode() due to this open() call. 212 * openCameraDevice() must not trigger AVAILABLE_OFF before NOT_AVAILABLE 213 * for all flash units that have become unavailable. 214 * 215 * 4. ICameraDevice.close() is called to close a camera device. The camera 216 * provider HAL must call ICameraProviderCallback::torchModeStatusChange() 217 * for all flash units that have now entered the AVAILABLE_OFF state and 218 * can be turned on by calling ICameraProvider::setTorchMode() again because 219 * of sufficient new camera resources being freed up by this close() call. 220 * 221 * Note that the camera service calling ICameraProvider::setTorchMode() 222 * successfully must trigger AVAILABLE_OFF or AVAILABLE_ON callback for the 223 * given camera device. Additionally it must trigger AVAILABLE_OFF callbacks 224 * for other previously-on torch modes if HAL cannot keep multiple devices' 225 * flashlights on simultaneously. 226 */ 227enum TorchModeStatus : uint32_t { 228 /** 229 * The flash unit is no longer available and the torch mode can not be 230 * turned on by calling setTorchMode(). If the torch mode was AVAILABLE_ON, 231 * the flashlight must be turned off by the provider HAL before the provider 232 * HAL calls torchModeStatusChange(). 233 */ 234 NOT_AVAILABLE = 0, 235 236 /** 237 * A torch mode has become off and is available to be turned on via 238 * ICameraProvider::setTorchMode(). This may happen in the following 239 * cases: 240 * 1. After the resources to turn on the torch mode have become available. 241 * 2. After ICameraProvider::setTorchMode() is called to turn off the torch 242 * mode. 243 * 3. After the camera service turned on the torch mode for some other 244 * camera device and the provider HAL had to turn off the torch modes 245 * of other camera device(s) that were previously on, due to lack of 246 * resources to keep them all on. 247 */ 248 AVAILABLE_OFF = 1, 249 250 /** 251 * A torch mode has become on and is available to be turned off via 252 * ICameraProvider::setTorchMode(). This can happen only after 253 * ICameraProvider::setTorchMode() has been called to turn on the torch mode. 254 */ 255 AVAILABLE_ON = 2, 256 257}; 258 259/** 260 * CameraResourceCost: 261 * 262 * Structure defining the abstract resource cost of opening a camera device, 263 * and any usage conflicts between multiple camera devices. 264 * 265 * Obtainable via ICameraDevice::getResourceCost() 266 */ 267struct CameraResourceCost { 268 /** 269 * The total resource "cost" of using this camera, represented as an integer 270 * value in the range [0, 100] where 100 represents total usage of the 271 * shared resource that is the limiting bottleneck of the camera subsystem. 272 * This may be a very rough estimate, and is used as a hint to the camera 273 * service to determine when to disallow multiple applications from 274 * simultaneously opening different cameras advertised by the camera 275 * service. 276 * 277 * The camera service must be able to simultaneously open and use any 278 * combination of camera devices exposed by the HAL where the sum of 279 * the resource costs of these cameras is <= 100. For determining cost, 280 * each camera device must be assumed to be configured and operating at 281 * the maximally resource-consuming framerate and stream size settings 282 * available in the configuration settings exposed for that device through 283 * the camera metadata. 284 * 285 * The camera service may still attempt to simultaneously open combinations 286 * of camera devices with a total resource cost > 100. This may succeed or 287 * fail. If this succeeds, combinations of configurations that are not 288 * supported due to resource constraints from having multiple open devices 289 * must fail during the configure calls. If the total resource cost is <= 290 * 100, open and configure must never fail for any stream configuration 291 * settings or other device capabilities that would normally succeed for a 292 * device when it is the only open camera device. 293 * 294 * This field may be used to determine whether background applications are 295 * allowed to use this camera device while other applications are using 296 * other camera devices. Note: multiple applications must never be allowed 297 * by the camera service to simultaneously open the same camera device. 298 * 299 * Example use cases: 300 * 301 * Ex. 1: Camera Device 0 = Back Camera 302 * Camera Device 1 = Front Camera 303 * - Using both camera devices causes a large framerate slowdown due to 304 * limited ISP bandwidth. 305 * 306 * Configuration: 307 * 308 * Camera Device 0 - resourceCost = 51 309 * conflicting_devices = empty 310 * Camera Device 1 - resourceCost = 51 311 * conflicting_devices = empty 312 * 313 * Result: 314 * 315 * Since the sum of the resource costs is > 100, if a higher-priority 316 * application has either device open, no lower-priority applications must 317 * be allowed by the camera service to open either device. If a 318 * lower-priority application is using a device that a higher-priority 319 * subsequently attempts to open, the lower-priority application must be 320 * forced to disconnect the the device. 321 * 322 * If the highest-priority application chooses, it may still attempt to 323 * open both devices (since these devices are not listed as conflicting in 324 * the conflicting_devices fields), but usage of these devices may fail in 325 * the open or configure calls. 326 * 327 * Ex. 2: Camera Device 0 = Left Back Camera 328 * Camera Device 1 = Right Back Camera 329 * Camera Device 2 = Combined stereo camera using both right and left 330 * back camera sensors used by devices 0, and 1 331 * Camera Device 3 = Front Camera 332 * - Due to do hardware constraints, up to two cameras may be open at 333 * once. The combined stereo camera may never be used at the same time 334 * as either of the two back camera devices (device 0, 1), and typically 335 * requires too much bandwidth to use at the same time as the front 336 * camera (device 3). 337 * 338 * Configuration: 339 * 340 * Camera Device 0 - resourceCost = 50 341 * conflicting_devices = { 2 } 342 * Camera Device 1 - resourceCost = 50 343 * conflicting_devices = { 2 } 344 * Camera Device 2 - resourceCost = 100 345 * conflicting_devices = { 0, 1 } 346 * Camera Device 3 - resourceCost = 50 347 * conflicting_devices = empty 348 * 349 * Result: 350 * 351 * Based on the conflicting_devices fields, the camera service guarantees 352 * that the following sets of open devices must never be allowed: { 1, 2 353 * }, { 0, 2 }. 354 * 355 * Based on the resourceCost fields, if a high-priority foreground 356 * application is using camera device 0, a background application would be 357 * allowed to open camera device 1 or 3 (but would be forced to disconnect 358 * it again if the foreground application opened another device). 359 * 360 * The highest priority application may still attempt to simultaneously 361 * open devices 0, 2, and 3, but the HAL may fail in open or configure 362 * calls for this combination. 363 * 364 * Ex. 3: Camera Device 0 = Back Camera 365 * Camera Device 1 = Front Camera 366 * Camera Device 2 = Low-power Front Camera that uses the same sensor 367 * as device 1, but only exposes image stream 368 * resolutions that can be used in low-power mode 369 * - Using both front cameras (device 1, 2) at the same time is impossible 370 * due a shared physical sensor. Using the back and "high-power" front 371 * camera (device 1) may be impossible for some stream configurations due 372 * to hardware limitations, but the "low-power" front camera option may 373 * always be used as it has special dedicated hardware. 374 * 375 * Configuration: 376 * 377 * Camera Device 0 - resourceCost = 100 378 * conflicting_devices = empty 379 * Camera Device 1 - resourceCost = 100 380 * conflicting_devices = { 2 } 381 * Camera Device 2 - resourceCost = 0 382 * conflicting_devices = { 1 } 383 * Result: 384 * 385 * Based on the conflicting_devices fields, the camera service guarantees 386 * that the following sets of open devices must never be allowed: 387 * { 1, 2 }. 388 * 389 * Based on the resourceCost fields, only the highest priority application 390 * may attempt to open both device 0 and 1 at the same time. If a 391 * higher-priority application is not using device 1 or 2, a low-priority 392 * background application may open device 2 (but must be forced to 393 * disconnect it if a higher-priority application subsequently opens 394 * device 1 or 2). 395 */ 396 uint32_t resourceCost; 397 398 /** 399 * An array of camera device IDs indicating other devices that cannot be 400 * simultaneously opened while this camera device is in use. 401 * 402 * This field is intended to be used to indicate that this camera device 403 * is a composite of several other camera devices, or otherwise has 404 * hardware dependencies that prohibit simultaneous usage. If there are no 405 * dependencies, an empty list may be returned to indicate this. 406 * 407 * The camera service must never simultaneously open any of the devices 408 * in this list while this camera device is open. 409 * 410 */ 411 vec<string> conflictingDevices; 412 413}; 414