1/* 2 * Copyright (C) 2019 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.automotive.evs@1.1; 18 19import @1.0::IEvsCamera; 20import @1.0::IEvsDisplay; 21import @1.0::EvsResult; 22import IEvsCameraStream; 23 24/** 25 * Represents a single camera and is the primary interface for capturing images. 26 */ 27interface IEvsCamera extends @1.0::IEvsCamera { 28 /** 29 * Returns the description of this camera. 30 * 31 * @return info The description of this camera. This must be the same value as 32 * reported by EvsEnumerator::getCameraList_1_1(). 33 */ 34 getCameraInfo_1_1() generates (CameraDesc info); 35 36 /** 37 * Returns the description of the physical camera device that backs this 38 * logical camera. 39 * 40 * If a requested device does not either exist or back this logical device, 41 * this method returns a null camera descriptor. And, if this is called on 42 * a physical camera device, this method is the same as getCameraInfo_1_1() 43 * method if a given device ID is matched. Otherwise, this will return a 44 * null camera descriptor. 45 * 46 * @param deviceId Physical camera device identifier string. 47 * @return info The description of a member physical camera device. 48 * This must be the same value as reported by 49 * EvsEnumerator::getCameraList_1_1(). 50 */ 51 getPhysicalCameraInfo(string deviceId) generates (CameraDesc info); 52 53 /** 54 * Requests to pause EVS camera stream events. 55 * 56 * Like stopVideoStream(), events may continue to arrive for some time 57 * after this call returns. Delivered frame buffers must be returned. 58 * 59 * @return result EvsResult::OK is returned if this call is successful. 60 */ 61 pauseVideoStream() generates (EvsResult result); 62 63 /** 64 * Requests to resume EVS camera stream. 65 * 66 * @return result EvsResult::OK is returned if this call is successful. 67 */ 68 resumeVideoStream() generates (EvsResult result); 69 70 /** 71 * Returns frame that were delivered by to the IEvsCameraStream. 72 * 73 * When done consuming a frame delivered to the IEvsCameraStream 74 * interface, it must be returned to the IEvsCamera for reuse. 75 * A small, finite number of buffers are available (possibly as small 76 * as one), and if the supply is exhausted, no further frames may be 77 * delivered until a buffer is returned. 78 * 79 * @param buffer Buffers to be returned. 80 * @return result Return EvsResult::OK if this call is successful. 81 */ 82 doneWithFrame_1_1(vec<BufferDesc> buffer) generates (EvsResult result); 83 84 /** 85 * Requests to be a master client. 86 * 87 * When multiple clients subscribe to a single camera hardware and one of 88 * them adjusts a camera parameter such as the contrast, it may disturb 89 * other clients' operations. Therefore, the client must call this method 90 * to be a master client. Once it becomes a master, it will be able to 91 * change camera parameters until either it dies or explicitly gives up the 92 * role. 93 * 94 * @return result EvsResult::OK if a master role is granted. 95 * EvsResult::OWNERSHIP_LOST if there is already a 96 * master client. 97 */ 98 setMaster() generates (EvsResult result); 99 100 /** 101 * Sets to be a master client forcibly. 102 * 103 * The client, which owns the display, has a high priority and can take over 104 * a master role from other clients without the display. 105 * 106 * @param display IEvsDisplay handle. If a given display is in either 107 * NOT_VISIBLE, VISIBLE_ON_NEXT_FRAME, or VISIBLE state, the 108 * calling client is considered as the high priority client 109 * and therefore allowed to take over a master role from 110 * existing master client. 111 * 112 * @return result EvsResult::OK if a master role is granted. 113 * EvsResult::INVALID_ARG if a given display handle is null 114 * or in valid states. 115 */ 116 forceMaster(IEvsDisplay display) generates (EvsResult result); 117 118 /** 119 * Retires from a master client role. 120 * 121 * @return result EvsResult::OK if this call is successful. 122 * EvsResult::INVALID_ARG if the caller client is not a 123 * master client. 124 */ 125 unsetMaster() generates (EvsResult result); 126 127 /** 128 * Retrieves a list of parameters this camera supports. 129 * 130 * @return params A list of CameraParam that this camera supports. 131 */ 132 getParameterList() generates (vec<CameraParam> params); 133 134 /** 135 * Requests a valid value range of a camera parameter 136 * 137 * @param id The identifier of camera parameter, CameraParam enum. 138 * 139 * @return min The lower bound of valid parameter value range. 140 * @return max The upper bound of valid parameter value range. 141 * @return step The resolution of values in valid range. 142 */ 143 getIntParameterRange(CameraParam id) 144 generates (int32_t min, int32_t max, int32_t step); 145 146 /** 147 * Requests to set a camera parameter. 148 * 149 * Only a request from the master client will be processed successfully. 150 * When this method is called on a logical camera device, it will be forwarded 151 * to each physical device and, if it fails to program any physical device, 152 * it will return an error code with the same number of effective values as 153 * the number of backing camera devices. 154 * 155 * @param id The identifier of camera parameter, CameraParam enum. 156 * value A desired parameter value. 157 * @return result EvsResult::OK if it succeeds to set a parameter. 158 * EvsResult::INVALID_ARG if either the request is 159 * not made by a master client, or a requested 160 * parameter is not supported. 161 * EvsResult::UNDERLYING_SERVICE_ERROR if it fails to 162 * program a value by any other reason. 163 * effectiveValue Programmed parameter values. This may differ 164 * from what the client gives if, for example, the 165 * driver does not support a target parameter. 166 */ 167 setIntParameter(CameraParam id, int32_t value) 168 generates (EvsResult result, vec<int32_t> effectiveValue); 169 170 /** 171 * Retrieves values of given camera parameter. 172 * 173 * @param id The identifier of camera parameter, CameraParam enum. 174 * @return result EvsResult::OK if it succeeds to read a parameter. 175 * EvsResult::INVALID_ARG if either a requested parameter is 176 * not supported. 177 * value Values of requested camera parameter, the same number of 178 * values as backing camera devices. 179 */ 180 getIntParameter(CameraParam id) generates(EvsResult result, vec<int32_t> value); 181 182 /** 183 * Request driver specific information from the HAL implementation. 184 * 185 * The values allowed for opaqueIdentifier are driver specific, 186 * but no value passed in may crash the driver. The driver should 187 * return EvsResult::INVALID_ARG for any unrecognized opaqueIdentifier. 188 * 189 * @param opaqueIdentifier An unique identifier of the information to 190 * request. 191 * @return result EvsResult::OK if the driver recognizes a given 192 * identifier. 193 * EvsResult::INVALID_ARG, otherwise. 194 * @return value Requested information. Zero-size vector is 195 * returned if the driver does not recognize a 196 * given identifier. 197 */ 198 getExtendedInfo_1_1(uint32_t opaqueIdentifier) 199 generates (EvsResult result, vec<uint8_t> value); 200 201 /** 202 * Send a driver specific value to the HAL implementation. 203 * 204 * This extension is provided to facilitate car specific 205 * extensions, but no HAL implementation may require this call 206 * in order to function in a default state. 207 * INVALID_ARG is returned if the opaqueValue is not meaningful to 208 * the driver implementation. 209 * 210 * @param opaqueIdentifier An unique identifier of the information to 211 * program. 212 * opaqueValue A value to program. 213 * @return result EvsResult::OK is returned if this call is successful. 214 * EvsResult::INVALID_ARG, otherwise. 215 */ 216 setExtendedInfo_1_1(uint32_t opaqueIdentifier, vec<uint8_t> opaqueValue) 217 generates (EvsResult result); 218 219 /** 220 * Import external buffers to capture frames 221 * 222 * This API must be called with a physical camera device identifier. 223 * 224 * @param buffers A list of buffers allocated by the caller. EvsCamera 225 * will use these buffers to capture frames, in addition to 226 * other buffers already in its buffer pool. 227 * @return result EvsResult::OK if it succeeds to import buffers. 228 * EvsResult::UNDERLYING_SERVICE_ERROR if this is called 229 * for logical camera devices or EVS fails to import 230 * buffers. 231 * delta The amount of buffer pool size changes after importing 232 * given buffers. 233 */ 234 importExternalBuffers(vec<BufferDesc> buffers) 235 generates (EvsResult result, int32_t delta); 236}; 237