/* * Copyright (C) 2016 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware.camera.device@3.2; import android.hardware.camera.common@1.0::types; import ICameraDeviceSession; import ICameraDeviceCallback; /** * Camera device HAL, first modern version * * Supports the android.hardware.Camera API, and the android.hardware.camera2 * API at LIMITED or better hardware level. * */ interface ICameraDevice { /** * Get camera device resource cost information. * * @return status Status code for the operation, one of: * OK: * On success * INTERNAL_ERROR: * An unexpected internal camera HAL error occurred, and the * resource cost is not available. * CAMERA_DISCONNECTED: * An external camera device has been disconnected, and is no longer * available. This camera device interface is now stale, and a new * instance must be acquired if the device is reconnected. All * subsequent calls on this interface must return * CAMERA_DISCONNECTED. * @return resourceCost * The resources required to open this camera device, or unspecified * values if status is not OK. */ getResourceCost() generates (Status status, CameraResourceCost resourceCost); /** * getCameraCharacteristics: * * Return the static camera information for this camera device. This * information may not change between consecutive calls. * * When an external camera is disconnected, its camera id becomes * invalid. Calling this method with this invalid camera id must result in * ILLEGAL_ARGUMENT; this may happen even before the device status callback * is invoked by the HAL. * * @return status Status code for the operation, one of: * OK: * On a successful open of the camera device. * INTERNAL_ERROR: * The camera device cannot be opened due to an internal * error. * CAMERA_DISCONNECTED: * An external camera device has been disconnected, and is no longer * available. This camera device interface is now stale, and a new * instance must be acquired if the device is reconnected. All * subsequent calls on this interface must return * CAMERA_DISCONNECTED. * * @return cameraCharacteristics * The static metadata for this camera device, or an empty metadata * structure if status is not OK. * */ getCameraCharacteristics() generates (Status status, CameraMetadata cameraCharacteristics); /** * setTorchMode: * * Turn on or off the torch mode of the flash unit associated with this * camera device. If the operation is successful, HAL must notify the * framework torch state by invoking * ICameraProviderCallback::torchModeStatusChange() with the new state. * * An active camera session has a higher priority accessing the flash * unit. When there are any resource conflicts, such as when open() is * called to fully activate a camera device, the provider must notify the * framework through ICameraProviderCallback::torchModeStatusChange() that * the torch mode has been turned off and the torch mode state has become * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode * become available again, the provider must notify the framework through * ICameraProviderCallback::torchModeStatusChange() that the torch mode * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to * be called. * * When the client calls setTorchMode() to turn on the torch mode of a flash * unit, if the HAL cannot keep multiple torch modes on simultaneously, the * HAL must turn off the torch mode(s) that were turned on by previous * setTorchMode() calls and notify the framework that the torch mode state * of those flash unit(s) has become TORCH_MODE_STATUS_AVAILABLE_OFF. * * @param torchMode The new mode to set the device flash unit to. * * @return status Status code for the operation, one of: * OK: * On a successful change to the torch state * INTERNAL_ERROR: * The flash unit cannot be operated due to an unexpected internal * error. * ILLEGAL_ARGUMENT: * The camera ID is unknown. * CAMERA_IN_USE: * This camera device has been opened, so the torch cannot be * controlled until it is closed. * MAX_CAMERAS_IN_USE: * Due to other camera devices being open, or due to other * resource constraints, the torch cannot be controlled currently. * METHOD_NOT_SUPPORTED: * This provider does not support direct operation of flashlight * torch mode. The framework must open the camera device and turn * the torch on through the device interface. * OPERATION_NOT_SUPPORTED: * This camera device does not have a flash unit. This can * be returned if and only if android.flash.info.available is * false. * CAMERA_DISCONNECTED: * An external camera device has been disconnected, and is no longer * available. This camera device interface is now stale, and a new * instance must be acquired if the device is reconnected. All * subsequent calls on this interface must return * CAMERA_DISCONNECTED. * */ setTorchMode(TorchMode mode) generates (Status status); /** * open: * * Power on and initialize this camera device for active use, returning a * session handle for active operations. * * @param callback Interface to invoke by the HAL for device asynchronous * events. For HALs newer than version 3.2, HAL must use castFrom * method to check the exact version of callback sent by camera service. * * @return status Status code for the operation, one of: * OK: * On a successful open of the camera device. * INTERNAL_ERROR: * The camera device cannot be opened due to an internal * error. * ILLEGAL_ARGUMENT: * The callbacks handle is invalid (for example, it is null). * CAMERA_IN_USE: * This camera device is already open. * MAX_CAMERAS_IN_USE: * The maximal number of camera devices that can be * opened concurrently were opened already. * CAMERA_DISCONNECTED: * This external camera device has been disconnected, and is no * longer available. This interface is now stale, and a new instance * must be acquired if the device is reconnected. All subsequent * calls on this interface must return CAMERA_DISCONNECTED. * @return session The interface to the newly-opened camera session, * or null if status is not OK. */ open(ICameraDeviceCallback callback) generates (Status status, ICameraDeviceSession session); /** * dumpState: * * Print out debugging state for the camera device. This may be called by * the framework when the camera service is asked for a debug dump, which * happens when using the dumpsys tool, or when capturing a bugreport. * * The passed-in file descriptor can be used to write debugging text using * dprintf() or write(). The text must be in ASCII encoding only. * * In case this camera device has been disconnected, the dump must not fail, * but may simply print out 'Device disconnected' or equivalent. * * Performance requirements: * * This must be a non-blocking call. The HAL should return from this call * in 1ms, must return from this call in 10ms. This call must avoid * deadlocks, as it may be called at any point during camera operation. * Any synchronization primitives used (such as mutex locks or semaphores) * must be acquired with a timeout. */ dumpState(handle fd); };