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.device@1.0; 18 19import android.hardware.camera.common@1.0::types; 20import ICameraDeviceCallback; 21import ICameraDevicePreviewCallback; 22 23/** 24 * Camera device HAL, legacy version 25 * 26 * DEPRECATED. New devices are strongly recommended to use Camera HAL v3.2 or 27 * newer. 28 * 29 * Supports the android.hardware.Camera API, and the android.hardware.camera2 30 * API in LEGACY mode only. 31 * 32 * Will be removed in the Android P release. 33 */ 34interface ICameraDevice { 35 36 /** 37 * Get camera device resource cost information. 38 * 39 * This method may be called at any time, including before open() 40 * 41 * @return status Status code for the operation, one of: 42 * OK: 43 * On success. 44 * INTERNAL_ERROR: 45 * An unexpected internal camera HAL error occurred, and the 46 * resource cost is not available. 47 * CAMERA_DISCONNECTED: 48 * An external camera device has been disconnected, and is no longer 49 * available. This camera device interface is now stale, and a new 50 * instance must be acquired if the device is reconnected. All 51 * subsequent calls on this interface must return 52 * CAMERA_DISCONNECTED. 53 * @return resourceCost 54 * The resources required to open this camera device, or unspecified 55 * values if status is not OK. 56 */ 57 getResourceCost() generates (Status status, CameraResourceCost resourceCost); 58 59 /** 60 * Get basic camera information. 61 * 62 * This method may be called at any time, including before open() 63 * 64 * @return status Status code for the operation, one of: 65 * OK: 66 * On success. 67 * INTERNAL_ERROR: 68 * An unexpected internal camera HAL error occurred, and the 69 * camera information is not available. 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 * @return info Basic information about this camera device, or unspecified 77 * values if status is not OK. 78 */ 79 getCameraInfo() generates (Status status, CameraInfo info); 80 81 /** 82 * setTorchMode: 83 * 84 * Turn on or off the torch mode of the flash unit associated with a given 85 * camera ID. If the operation is successful, HAL must notify the framework 86 * torch state by invoking 87 * ICameraProviderCallback::torchModeStatusChange() with the new state. 88 * 89 * The camera device has a higher priority accessing the flash unit. When 90 * there are any resource conflicts, such as when open() is called to fully 91 * activate a camera device, the provider must notify the framework through 92 * ICameraProviderCallback::torchModeStatusChange() that the torch mode has 93 * been turned off and the torch mode state has become 94 * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode 95 * become available again, the provider must notify the framework through 96 * ICameraProviderCallback::torchModeStatusChange() that the torch mode 97 * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to 98 * be called. 99 * 100 * When the framework calls setTorchMode() to turn on the torch mode of a 101 * flash unit, if HAL cannot keep multiple torch modes on simultaneously, 102 * HAL must turn off the torch mode that was turned on by 103 * a previous setTorchMode() call and notify the framework that the torch 104 * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF. 105 * 106 * @param torchMode The new mode to set the device flash unit to. 107 * 108 * @return status Status code for the operation, one of: 109 * OK: 110 * On a successful change to the torch state. 111 * INTERNAL_ERROR: 112 * The flash unit cannot be operated due to an unexpected internal 113 * error. 114 * ILLEGAL_ARGUMENT: 115 * The camera ID is unknown. 116 * CAMERA_IN_USE: 117 * This camera device has been opened, so the torch cannot be 118 * controlled until it is closed. 119 * MAX_CAMERAS_IN_USE: 120 * Due to other camera devices being open, or due to other 121 * resource constraints, the torch cannot be controlled currently. 122 * METHOD_NOT_SUPPORTED: 123 * This provider does not support direct operation of flashlight 124 * torch mode. The framework must open the camera device and turn 125 * the torch on through the device interface. 126 * OPERATION_NOT_SUPPORTED: 127 * This camera device does not have a flash unit. This must 128 * be returned if and only if parameter key flash-mode-values is not present. 129 * CAMERA_DISCONNECTED: 130 * An external camera device has been disconnected, and is no longer 131 * available. This camera device interface is now stale, and a new 132 * instance must be acquired if the device is reconnected. All 133 * subsequent calls on this interface must return 134 * CAMERA_DISCONNECTED. 135 * 136 */ 137 setTorchMode(TorchMode mode) generates (Status status); 138 139 /** 140 * Dump state of the camera hardware. 141 * 142 * This must be callable at any time, whether the device is open or not. 143 * 144 * @param fd A native handle with one valid file descriptor. The descriptor 145 * must be able to be used with dprintf() or equivalent to dump the 146 * state of this camera device into the camera service dumpsys output. 147 * 148 * @return status The status code for this operation. 149 */ 150 dumpState(handle fd) generates (Status status); 151 152 /** 153 * Open the camera device for active use. 154 * 155 * All methods besides getResourceCost(), getCameraInfo(), setTorchMode(), 156 * and dump() must not be called unless open() has been called successfully, 157 * and close() has not yet been called. 158 * 159 * @param callback Interface to invoke by the HAL for device callbacks. 160 * @return status Status code for the operation, one of: 161 * OK: 162 * On a successful open of the camera device. 163 * INTERNAL_ERROR: 164 * The camera device cannot be opened due to an internal 165 * error. 166 * ILLEGAL_ARGUMENT: 167 * The callback handle is invalid (for example, it is null). 168 * CAMERA_IN_USE: 169 * This camera device is already open. 170 * MAX_CAMERAS_IN_USE: 171 * The maximal number of camera devices that can be 172 * opened concurrently were opened already. 173 * CAMERA_DISCONNECTED: 174 * This external camera device has been disconnected, and is no 175 * longer available. This interface is now stale, and a new instance 176 * must be acquired if the device is reconnected. All subsequent 177 * calls on this interface must return CAMERA_DISCONNECTED. 178 */ 179 open(ICameraDeviceCallback callback) generates (Status status); 180 181 182 /***** 183 * All methods below this point must only be called between a successful 184 * open() call and a close() call. 185 */ 186 187 /** Set the callback interface through which preview frames are sent */ 188 setPreviewWindow(ICameraDevicePreviewCallback window) 189 generates (Status status); 190 191 /** 192 * Enable a message, or set of messages. 193 * 194 * @param msgType The bitfield of messages to enable. 195 */ 196 enableMsgType(FrameCallbackFlags msgType); 197 198 /** 199 * Disable a message, or a set of messages. 200 * 201 * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera 202 * HAL must not rely on its client to call releaseRecordingFrame() to 203 * release video recording frames sent out by the cameral HAL before and 204 * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL 205 * clients must not modify/access any video recording frame after calling 206 * disableMsgType(CAMERA_MSG_VIDEO_FRAME). 207 * 208 * @param msgType The bitfield of messages to disable. 209 */ 210 disableMsgType(FrameCallbackFlags msgType); 211 212 /** 213 * Query whether a message, or a set of messages, is enabled. Note that 214 * this is operates as an AND, if any of the messages queried are off, this 215 * must return false. 216 * 217 * @param msgType The bitfield of messages to query. 218 * @return enabled Whether all the specified flags are enabled. 219 */ 220 msgTypeEnabled(FrameCallbackFlags msgType) generates (bool enabled); 221 222 /** 223 * Start preview mode. 224 * 225 * @return status The status code for this operation. 226 */ 227 startPreview() generates (Status status); 228 229 /** 230 * Stop a previously started preview. 231 */ 232 stopPreview(); 233 234 /** 235 * Returns true if preview is enabled. 236 * 237 * @return enabled Whether preview is currently enabled. 238 */ 239 previewEnabled() generates (bool enabled); 240 241 /** 242 * Request the camera HAL to store meta data or real YUV data in the video 243 * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If 244 * it is not called, the default camera HAL behavior is to store real YUV 245 * data in the video buffers. 246 * 247 * This method must be called before startRecording() in order to be 248 * effective. 249 * 250 * If meta data is stored in the video buffers, it is up to the receiver of 251 * the video buffers to interpret the contents and to find the actual frame 252 * data with the help of the meta data in the buffer. How this is done is 253 * outside of the scope of this method. 254 * 255 * Some camera HALs may not support storing meta data in the video buffers, 256 * but all camera HALs must support storing real YUV data in the video 257 * buffers. If the camera HAL does not support storing the meta data in the 258 * video buffers when it is requested to do do, INVALID_OPERATION must be 259 * returned. It is very useful for the camera HAL to pass meta data rather 260 * than the actual frame data directly to the video encoder, since the 261 * amount of the uncompressed frame data can be very large if video size is 262 * large. 263 * 264 * @param enable Set to true to instruct the camera HAL to store meta data 265 * in the video buffers; false to instruct the camera HAL to store real 266 * YUV data in the video buffers. 267 * 268 * @return status OK on success. 269 */ 270 storeMetaDataInBuffers(bool enable) generates (Status status); 271 272 /** 273 * Start record mode. 274 * 275 * When a record image is available, a CAMERA_MSG_VIDEO_FRAME message is 276 * sent with the corresponding frame. Every record frame must be released by 277 * a camera HAL client via releaseRecordingFrame() before the client calls 278 * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls 279 * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's 280 * responsibility to manage the life-cycle of the video recording frames, 281 * and the client must not modify/access any video recording frames. 282 * 283 * @return status The status code for the operation. 284 */ 285 startRecording() generates (Status status); 286 287 /** 288 * Stop a previously started recording. 289 */ 290 stopRecording(); 291 292 /** 293 * Returns true if recording is enabled. 294 * 295 * @return enabled True if recording is currently active. 296 */ 297 recordingEnabled() generates (bool enabled); 298 299 /** 300 * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME in 301 * dataCallbackTimestamp. 302 * 303 * It is camera HAL client's responsibility to release video recording 304 * frames sent out by the camera HAL before the camera HAL receives a call 305 * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to 306 * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's 307 * responsibility to manage the life-cycle of the video recording frames. 308 * 309 * @param memId The memory buffer to release a recording frame from. 310 * @param bufferIndex The specific buffer index to return to the HAL. 311 */ 312 releaseRecordingFrame(MemoryId memId, uint32_t bufferIndex); 313 314 /** 315 * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME in 316 * handleCallbackTimestamp. 317 * 318 * It is camera HAL client's responsibility to release video recording 319 * frames sent out by the camera HAL before the camera HAL receives a call 320 * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to 321 * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's 322 * responsibility to manage the life-cycle of the video recording frames. 323 * 324 * @param memId The memory buffer to release a recording frame from. 325 * @param bufferIndex The specific buffer index to return to the HAL. 326 * @param frame The handle for a released video frame 327 */ 328 releaseRecordingFrameHandle(MemoryId memId, uint32_t bufferIndex, handle frame); 329 330 /** 331 * Release a batch of record frames previously returned by CAMERA_MSG_VIDEO_FRAME 332 * in handleCallbackTimestampBatch. 333 * 334 * It is camera HAL client's responsibility to release video recording 335 * frames sent out by the camera HAL before the camera HAL receives a call 336 * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to 337 * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's 338 * responsibility to manage the life-cycle of the video recording frames. 339 * 340 * @param batch A batch of recording frames to be released by camera HAL. 341 */ 342 releaseRecordingFrameHandleBatch(vec<VideoFrameMessage> batch); 343 344 /** 345 * Start auto focus. 346 * 347 * The notification callback routine is called with 348 * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() can be 349 * called again after that if another auto focus is needed. 350 * 351 * @return status The status code for this operation. 352 */ 353 autoFocus() generates (Status status); 354 355 /** 356 * Cancels auto-focus function. 357 * 358 * If the auto-focus is still in progress, this function must cancel 359 * it. Whether the auto-focus is in progress or not, this function must 360 * return the focus position to the default. If the camera does not support 361 * auto-focus, this is a no-op. 362 * 363 * @return status The status code for this operation. 364 */ 365 cancelAutoFocus() generates (Status status); 366 367 /** 368 * Take a picture. 369 * 370 * @return status The status code for this operation. 371 */ 372 takePicture() generates (Status status); 373 374 /** 375 * Cancel a picture that was started with takePicture. Calling this method 376 * when no picture is being taken is a no-op. 377 * 378 * @return status The status code for this operation. 379 */ 380 cancelPicture() generates (Status status); 381 382 /** 383 * Set the camera parameters. 384 * 385 * @param params The parameter string, consisting of 386 * '<key1>=<value1>; ...;<keyN>=<valueN>'. 387 * @return status The status code for this operation: 388 * OK: Parameter update was successful 389 * ILLEGAL_ARGUMENT: At least one parameter was invalid or not supported 390 * 391 */ 392 setParameters(string params) generates (Status status); 393 394 /** 395 * Retrieve the camera parameters. 396 */ 397 getParameters() generates (string parms); 398 399 /** 400 * Send command to camera driver. 401 * The meaning of the arguments is defined by the value of cmd, documented 402 * in the CommandType definition. 403 * 404 * @param cmd The command to invoke. 405 * @param arg1 The first argument for the command, if needed. 406 * @param arg2 The second argument for the command, if needed. 407 * 408 * @return status The status code for this operation. 409 */ 410 sendCommand(CommandType cmd, int32_t arg1, int32_t arg2) 411 generates (Status status); 412 413 /** 414 * Release the hardware resources owned by this object, shutting down the 415 * camera device. 416 */ 417 close(); 418 419}; 420