1 /* 2 * Copyright (C) 2013-2018 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 #ifndef ANDROID_SERVERS_CAMERA_CAMERADEVICEBASE_H 18 #define ANDROID_SERVERS_CAMERA_CAMERADEVICEBASE_H 19 20 #include <list> 21 22 #include <utils/RefBase.h> 23 #include <utils/String8.h> 24 #include <utils/String16.h> 25 #include <utils/Vector.h> 26 #include <utils/KeyedVector.h> 27 #include <utils/Timers.h> 28 #include <utils/List.h> 29 30 #include "hardware/camera2.h" 31 #include "hardware/camera3.h" 32 #include "camera/CameraMetadata.h" 33 #include "camera/CaptureResult.h" 34 #include "gui/IGraphicBufferProducer.h" 35 #include "device3/Camera3StreamInterface.h" 36 #include "binder/Status.h" 37 38 namespace android { 39 40 class CameraProviderManager; 41 42 // Mapping of output stream index to surface ids 43 typedef std::unordered_map<int, std::vector<size_t> > SurfaceMap; 44 45 /** 46 * Base interface for version >= 2 camera device classes, which interface to 47 * camera HAL device versions >= 2. 48 */ 49 class CameraDeviceBase : public virtual RefBase { 50 public: 51 virtual ~CameraDeviceBase(); 52 53 /** 54 * The device's camera ID 55 */ 56 virtual const String8& getId() const = 0; 57 58 /** 59 * The device vendor tag ID 60 */ 61 virtual metadata_vendor_id_t getVendorTagId() const = 0; 62 63 virtual status_t initialize(sp<CameraProviderManager> manager, const String8& monitorTags) = 0; 64 virtual status_t disconnect() = 0; 65 66 virtual status_t dump(int fd, const Vector<String16> &args) = 0; 67 68 /** 69 * The device's static characteristics metadata buffer 70 */ 71 virtual const CameraMetadata& info() const = 0; 72 /** 73 * The physical camera device's static characteristics metadata buffer 74 */ 75 virtual const CameraMetadata& info(const String8& physicalId) const = 0; 76 77 struct PhysicalCameraSettings { 78 std::string cameraId; 79 CameraMetadata metadata; 80 }; 81 typedef List<PhysicalCameraSettings> PhysicalCameraSettingsList; 82 83 /** 84 * Submit request for capture. The CameraDevice takes ownership of the 85 * passed-in buffer. 86 * Output lastFrameNumber is the expected frame number of this request. 87 */ 88 virtual status_t capture(CameraMetadata &request, int64_t *lastFrameNumber = NULL) = 0; 89 90 /** 91 * Submit a list of requests. 92 * Output lastFrameNumber is the expected last frame number of the list of requests. 93 */ 94 virtual status_t captureList(const List<const PhysicalCameraSettingsList> &requests, 95 const std::list<const SurfaceMap> &surfaceMaps, 96 int64_t *lastFrameNumber = NULL) = 0; 97 98 /** 99 * Submit request for streaming. The CameraDevice makes a copy of the 100 * passed-in buffer and the caller retains ownership. 101 * Output lastFrameNumber is the last frame number of the previous streaming request. 102 */ 103 virtual status_t setStreamingRequest(const CameraMetadata &request, 104 int64_t *lastFrameNumber = NULL) = 0; 105 106 /** 107 * Submit a list of requests for streaming. 108 * Output lastFrameNumber is the last frame number of the previous streaming request. 109 */ 110 virtual status_t setStreamingRequestList(const List<const PhysicalCameraSettingsList> &requests, 111 const std::list<const SurfaceMap> &surfaceMaps, 112 int64_t *lastFrameNumber = NULL) = 0; 113 114 /** 115 * Clear the streaming request slot. 116 * Output lastFrameNumber is the last frame number of the previous streaming request. 117 */ 118 virtual status_t clearStreamingRequest(int64_t *lastFrameNumber = NULL) = 0; 119 120 /** 121 * Wait until a request with the given ID has been dequeued by the 122 * HAL. Returns TIMED_OUT if the timeout duration is reached. Returns 123 * immediately if the latest request received by the HAL has this id. 124 */ 125 virtual status_t waitUntilRequestReceived(int32_t requestId, 126 nsecs_t timeout) = 0; 127 128 /** 129 * Create an output stream of the requested size, format, rotation and dataspace 130 * 131 * For HAL_PIXEL_FORMAT_BLOB formats, the width and height should be the 132 * logical dimensions of the buffer, not the number of bytes. 133 */ 134 virtual status_t createStream(sp<Surface> consumer, 135 uint32_t width, uint32_t height, int format, 136 android_dataspace dataSpace, camera3_stream_rotation_t rotation, int *id, 137 const String8& physicalCameraId, 138 std::vector<int> *surfaceIds = nullptr, 139 int streamSetId = camera3::CAMERA3_STREAM_SET_ID_INVALID, 140 bool isShared = false, uint64_t consumerUsage = 0) = 0; 141 142 /** 143 * Create an output stream of the requested size, format, rotation and 144 * dataspace with a number of consumers. 145 * 146 * For HAL_PIXEL_FORMAT_BLOB formats, the width and height should be the 147 * logical dimensions of the buffer, not the number of bytes. 148 */ 149 virtual status_t createStream(const std::vector<sp<Surface>>& consumers, 150 bool hasDeferredConsumer, uint32_t width, uint32_t height, int format, 151 android_dataspace dataSpace, camera3_stream_rotation_t rotation, int *id, 152 const String8& physicalCameraId, 153 std::vector<int> *surfaceIds = nullptr, 154 int streamSetId = camera3::CAMERA3_STREAM_SET_ID_INVALID, 155 bool isShared = false, uint64_t consumerUsage = 0) = 0; 156 157 /** 158 * Create an input stream of width, height, and format. 159 * 160 * Return value is the stream ID if non-negative and an error if negative. 161 */ 162 virtual status_t createInputStream(uint32_t width, uint32_t height, 163 int32_t format, /*out*/ int32_t *id) = 0; 164 165 struct StreamInfo { 166 uint32_t width; 167 uint32_t height; 168 169 uint32_t format; 170 bool formatOverridden; 171 uint32_t originalFormat; 172 173 android_dataspace dataSpace; 174 bool dataSpaceOverridden; 175 android_dataspace originalDataSpace; 176 StreamInfoStreamInfo177 StreamInfo() : width(0), height(0), format(0), formatOverridden(false), originalFormat(0), 178 dataSpace(HAL_DATASPACE_UNKNOWN), dataSpaceOverridden(false), 179 originalDataSpace(HAL_DATASPACE_UNKNOWN) {} 180 /** 181 * Check whether the format matches the current or the original one in case 182 * it got overridden. 183 */ matchFormatStreamInfo184 bool matchFormat(uint32_t clientFormat) const { 185 if ((formatOverridden && (originalFormat == clientFormat)) || 186 (format == clientFormat)) { 187 return true; 188 } 189 return false; 190 } 191 192 /** 193 * Check whether the dataspace matches the current or the original one in case 194 * it got overridden. 195 */ matchDataSpaceStreamInfo196 bool matchDataSpace(android_dataspace clientDataSpace) const { 197 if ((dataSpaceOverridden && (originalDataSpace == clientDataSpace)) || 198 (dataSpace == clientDataSpace)) { 199 return true; 200 } 201 return false; 202 } 203 204 }; 205 206 /** 207 * Get information about a given stream. 208 */ 209 virtual status_t getStreamInfo(int id, StreamInfo *streamInfo) = 0; 210 211 /** 212 * Set stream gralloc buffer transform 213 */ 214 virtual status_t setStreamTransform(int id, int transform) = 0; 215 216 /** 217 * Delete stream. Must not be called if there are requests in flight which 218 * reference that stream. 219 */ 220 virtual status_t deleteStream(int id) = 0; 221 222 /** 223 * Take the currently-defined set of streams and configure the HAL to use 224 * them. This is a long-running operation (may be several hundered ms). 225 * 226 * The device must be idle (see waitUntilDrained) before calling this. 227 * 228 * Returns OK on success; otherwise on error: 229 * - BAD_VALUE if the set of streams was invalid (e.g. fmts or sizes) 230 * - INVALID_OPERATION if the device was in the wrong state 231 */ 232 virtual status_t configureStreams(const CameraMetadata& sessionParams, 233 int operatingMode = 0) = 0; 234 235 // get the buffer producer of the input stream 236 virtual status_t getInputBufferProducer( 237 sp<IGraphicBufferProducer> *producer) = 0; 238 239 /** 240 * Create a metadata buffer with fields that the HAL device believes are 241 * best for the given use case 242 */ 243 virtual status_t createDefaultRequest(int templateId, 244 CameraMetadata *request) = 0; 245 246 /** 247 * Wait until all requests have been processed. Returns INVALID_OPERATION if 248 * the streaming slot is not empty, or TIMED_OUT if the requests haven't 249 * finished processing in 10 seconds. 250 */ 251 virtual status_t waitUntilDrained() = 0; 252 253 /** 254 * Get Jpeg buffer size for a given jpeg resolution. 255 * Negative values are error codes. 256 */ 257 virtual ssize_t getJpegBufferSize(uint32_t width, uint32_t height) const = 0; 258 259 /** 260 * Abstract class for HAL notification listeners 261 */ 262 class NotificationListener : public virtual RefBase { 263 public: 264 // The set of notifications is a merge of the notifications required for 265 // API1 and API2. 266 267 // Required for API 1 and 2 268 virtual void notifyError(int32_t errorCode, 269 const CaptureResultExtras &resultExtras) = 0; 270 271 // Required only for API2 272 virtual void notifyIdle() = 0; 273 virtual void notifyShutter(const CaptureResultExtras &resultExtras, 274 nsecs_t timestamp) = 0; 275 virtual void notifyPrepared(int streamId) = 0; 276 virtual void notifyRequestQueueEmpty() = 0; 277 278 // Required only for API1 279 virtual void notifyAutoFocus(uint8_t newState, int triggerId) = 0; 280 virtual void notifyAutoExposure(uint8_t newState, int triggerId) = 0; 281 virtual void notifyAutoWhitebalance(uint8_t newState, 282 int triggerId) = 0; 283 virtual void notifyRepeatingRequestError(long lastFrameNumber) = 0; 284 protected: 285 virtual ~NotificationListener(); 286 }; 287 288 /** 289 * Connect HAL notifications to a listener. Overwrites previous 290 * listener. Set to NULL to stop receiving notifications. 291 */ 292 virtual status_t setNotifyCallback(wp<NotificationListener> listener) = 0; 293 294 /** 295 * Whether the device supports calling notifyAutofocus, notifyAutoExposure, 296 * and notifyAutoWhitebalance; if this returns false, the client must 297 * synthesize these notifications from received frame metadata. 298 */ 299 virtual bool willNotify3A() = 0; 300 301 /** 302 * Wait for a new frame to be produced, with timeout in nanoseconds. 303 * Returns TIMED_OUT when no frame produced within the specified duration 304 * May be called concurrently to most methods, except for getNextFrame 305 */ 306 virtual status_t waitForNextFrame(nsecs_t timeout) = 0; 307 308 /** 309 * Get next capture result frame from the result queue. Returns NOT_ENOUGH_DATA 310 * if the queue is empty; caller takes ownership of the metadata buffer inside 311 * the capture result object's metadata field. 312 * May be called concurrently to most methods, except for waitForNextFrame. 313 */ 314 virtual status_t getNextResult(CaptureResult *frame) = 0; 315 316 /** 317 * Trigger auto-focus. The latest ID used in a trigger autofocus or cancel 318 * autofocus call will be returned by the HAL in all subsequent AF 319 * notifications. 320 */ 321 virtual status_t triggerAutofocus(uint32_t id) = 0; 322 323 /** 324 * Cancel auto-focus. The latest ID used in a trigger autofocus/cancel 325 * autofocus call will be returned by the HAL in all subsequent AF 326 * notifications. 327 */ 328 virtual status_t triggerCancelAutofocus(uint32_t id) = 0; 329 330 /** 331 * Trigger pre-capture metering. The latest ID used in a trigger pre-capture 332 * call will be returned by the HAL in all subsequent AE and AWB 333 * notifications. 334 */ 335 virtual status_t triggerPrecaptureMetering(uint32_t id) = 0; 336 337 /** 338 * Flush all pending and in-flight requests. Blocks until flush is 339 * complete. 340 * Output lastFrameNumber is the last frame number of the previous streaming request. 341 */ 342 virtual status_t flush(int64_t *lastFrameNumber = NULL) = 0; 343 344 /** 345 * Prepare stream by preallocating buffers for it asynchronously. 346 * Calls notifyPrepared() once allocation is complete. 347 */ 348 virtual status_t prepare(int streamId) = 0; 349 350 /** 351 * Free stream resources by dumping its unused gralloc buffers. 352 */ 353 virtual status_t tearDown(int streamId) = 0; 354 355 /** 356 * Add buffer listener for a particular stream in the device. 357 */ 358 virtual status_t addBufferListenerForStream(int streamId, 359 wp<camera3::Camera3StreamBufferListener> listener) = 0; 360 361 /** 362 * Prepare stream by preallocating up to maxCount buffers for it asynchronously. 363 * Calls notifyPrepared() once allocation is complete. 364 */ 365 virtual status_t prepare(int maxCount, int streamId) = 0; 366 367 /** 368 * Set the deferred consumer surface and finish the rest of the stream configuration. 369 */ 370 virtual status_t setConsumerSurfaces(int streamId, 371 const std::vector<sp<Surface>>& consumers, std::vector<int> *surfaceIds /*out*/) = 0; 372 373 /** 374 * Update a given stream. 375 */ 376 virtual status_t updateStream(int streamId, const std::vector<sp<Surface>> &newSurfaces, 377 const std::vector<android::camera3::OutputStreamInfo> &outputInfo, 378 const std::vector<size_t> &removedSurfaceIds, 379 KeyedVector<sp<Surface>, size_t> *outputMap/*out*/) = 0; 380 381 /** 382 * Drop buffers for stream of streamId if dropping is true. If dropping is false, do not 383 * drop buffers for stream of streamId. 384 */ 385 virtual status_t dropStreamBuffers(bool /*dropping*/, int /*streamId*/) = 0; 386 }; 387 388 }; // namespace android 389 390 #endif 391