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