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 17 package android.hardware.camera.device@3.2; 18 19 import android.hardware.camera.common@1.0::types; 20 import ICameraDeviceSession; 21 import ICameraDeviceCallback; 22 23 /** 24 * Camera device HAL, first modern version 25 * 26 * Supports the android.hardware.Camera API, and the android.hardware.camera2 27 * API at LIMITED or better hardware level. 28 * 29 */ 30 interface ICameraDevice { 31 32 /** 33 * Get camera device resource cost information. 34 * 35 * @return status Status code for the operation, one of: 36 * OK: 37 * On success 38 * INTERNAL_ERROR: 39 * An unexpected internal camera HAL error occurred, and the 40 * resource cost is not available. 41 * CAMERA_DISCONNECTED: 42 * An external camera device has been disconnected, and is no longer 43 * available. This camera device interface is now stale, and a new 44 * instance must be acquired if the device is reconnected. All 45 * subsequent calls on this interface must return 46 * CAMERA_DISCONNECTED. 47 * @return resourceCost 48 * The resources required to open this camera device, or unspecified 49 * values if status is not OK. 50 */ 51 getResourceCost() generates (Status status, CameraResourceCost resourceCost); 52 53 /** 54 * getCameraCharacteristics: 55 * 56 * Return the static camera information for this camera device. This 57 * information may not change between consecutive calls. 58 * 59 * When an external camera is disconnected, its camera id becomes 60 * invalid. Calling this method with this invalid camera id must result in 61 * ILLEGAL_ARGUMENT; this may happen even before the device status callback 62 * is invoked by the HAL. 63 * 64 * @return status Status code for the operation, one of: 65 * OK: 66 * On a successful open of the camera device. 67 * INTERNAL_ERROR: 68 * The camera device cannot be opened due to an internal 69 * error. 70 * CAMERA_DISCONNECTED: 71 * An external camera device has been disconnected, and is no longer 72 * available. This camera device interface is now stale, and a new 73 * instance must be acquired if the device is reconnected. All 74 * subsequent calls on this interface must return 75 * CAMERA_DISCONNECTED. 76 * 77 * @return cameraCharacteristics 78 * The static metadata for this camera device, or an empty metadata 79 * structure if status is not OK. 80 * 81 */ 82 getCameraCharacteristics() generates 83 (Status status, CameraMetadata cameraCharacteristics); 84 85 /** 86 * setTorchMode: 87 * 88 * Turn on or off the torch mode of the flash unit associated with this 89 * camera device. If the operation is successful, HAL must notify the 90 * framework torch state by invoking 91 * ICameraProviderCallback::torchModeStatusChange() with the new state. 92 * 93 * An active camera session has a higher priority accessing the flash 94 * unit. When there are any resource conflicts, such as when open() is 95 * called to fully activate a camera device, the provider must notify the 96 * framework through ICameraProviderCallback::torchModeStatusChange() that 97 * the torch mode has been turned off and the torch mode state has become 98 * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode 99 * become available again, the provider must notify the framework through 100 * ICameraProviderCallback::torchModeStatusChange() that the torch mode 101 * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to 102 * be called. 103 * 104 * When the client calls setTorchMode() to turn on the torch mode of a flash 105 * unit, if the HAL cannot keep multiple torch modes on simultaneously, the 106 * HAL must turn off the torch mode(s) that were turned on by previous 107 * setTorchMode() calls and notify the framework that the torch mode state 108 * of those flash unit(s) has become TORCH_MODE_STATUS_AVAILABLE_OFF. 109 * 110 * @param torchMode The new mode to set the device flash unit to. 111 * 112 * @return status Status code for the operation, one of: 113 * OK: 114 * On a successful change to the torch state 115 * INTERNAL_ERROR: 116 * The flash unit cannot be operated due to an unexpected internal 117 * error. 118 * ILLEGAL_ARGUMENT: 119 * The camera ID is unknown. 120 * CAMERA_IN_USE: 121 * This camera device has been opened, so the torch cannot be 122 * controlled until it is closed. 123 * MAX_CAMERAS_IN_USE: 124 * Due to other camera devices being open, or due to other 125 * resource constraints, the torch cannot be controlled currently. 126 * METHOD_NOT_SUPPORTED: 127 * This provider does not support direct operation of flashlight 128 * torch mode. The framework must open the camera device and turn 129 * the torch on through the device interface. 130 * OPERATION_NOT_SUPPORTED: 131 * This camera device does not have a flash unit. This can 132 * be returned if and only if android.flash.info.available is 133 * false. 134 * CAMERA_DISCONNECTED: 135 * An external camera device has been disconnected, and is no longer 136 * available. This camera device interface is now stale, and a new 137 * instance must be acquired if the device is reconnected. All 138 * subsequent calls on this interface must return 139 * CAMERA_DISCONNECTED. 140 * 141 */ 142 setTorchMode(TorchMode mode) generates (Status status); 143 144 /** 145 * open: 146 * 147 * Power on and initialize this camera device for active use, returning a 148 * session handle for active operations. 149 * 150 * @param callback Interface to invoke by the HAL for device asynchronous 151 * events. 152 * @return status Status code for the operation, one of: 153 * OK: 154 * On a successful open of the camera device. 155 * INTERNAL_ERROR: 156 * The camera device cannot be opened due to an internal 157 * error. 158 * ILLEGAL_ARGUMENT: 159 * The callbacks handle is invalid (for example, it is null). 160 * CAMERA_IN_USE: 161 * This camera device is already open. 162 * MAX_CAMERAS_IN_USE: 163 * The maximal number of camera devices that can be 164 * opened concurrently were opened already. 165 * CAMERA_DISCONNECTED: 166 * This external camera device has been disconnected, and is no 167 * longer available. This interface is now stale, and a new instance 168 * must be acquired if the device is reconnected. All subsequent 169 * calls on this interface must return CAMERA_DISCONNECTED. 170 * @return session The interface to the newly-opened camera session, 171 * or null if status is not OK. 172 */ 173 open(ICameraDeviceCallback callback) generates 174 (Status status, ICameraDeviceSession session); 175 176 /** 177 * dumpState: 178 * 179 * Print out debugging state for the camera device. This may be called by 180 * the framework when the camera service is asked for a debug dump, which 181 * happens when using the dumpsys tool, or when capturing a bugreport. 182 * 183 * The passed-in file descriptor can be used to write debugging text using 184 * dprintf() or write(). The text must be in ASCII encoding only. 185 * 186 * In case this camera device has been disconnected, the dump must not fail, 187 * but may simply print out 'Device disconnected' or equivalent. 188 * 189 * Performance requirements: 190 * 191 * This must be a non-blocking call. The HAL should return from this call 192 * in 1ms, must return from this call in 10ms. This call must avoid 193 * deadlocks, as it may be called at any point during camera operation. 194 * Any synchronization primitives used (such as mutex locks or semaphores) 195 * must be acquired with a timeout. 196 */ 197 dumpState(handle fd); 198 199 }; 200
