Camera3Stream.h revision e02e932d2210bd513bb8283840bbe24b58d28620
1/* 2 * Copyright (C) 2013 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_CAMERA3_STREAM_H 18#define ANDROID_SERVERS_CAMERA3_STREAM_H 19 20#include <gui/Surface.h> 21#include <utils/RefBase.h> 22#include <utils/String8.h> 23#include <utils/String16.h> 24#include <utils/List.h> 25 26#include "hardware/camera3.h" 27 28#include "Camera3StreamBufferListener.h" 29#include "Camera3StreamInterface.h" 30 31namespace android { 32 33namespace camera3 { 34 35/** 36 * A class for managing a single stream of input or output data from the camera 37 * device. 38 * 39 * The stream has an internal state machine to track whether it's 40 * connected/configured/etc. 41 * 42 * States: 43 * 44 * STATE_ERROR: A serious error has occurred, stream is unusable. Outstanding 45 * buffers may still be returned. 46 * 47 * STATE_CONSTRUCTED: The stream is ready for configuration, but buffers cannot 48 * be gotten yet. Not connected to any endpoint, no buffers are registered 49 * with the HAL. 50 * 51 * STATE_IN_CONFIG: Configuration has started, but not yet concluded. During this 52 * time, the usage, max_buffers, and priv fields of camera3_stream returned by 53 * startConfiguration() may be modified. 54 * 55 * STATE_IN_RE_CONFIG: Configuration has started, and the stream has been 56 * configured before. Need to track separately from IN_CONFIG to avoid 57 * re-registering buffers with HAL. 58 * 59 * STATE_CONFIGURED: Stream is configured, and has registered buffers with the 60 * HAL (if necessary). The stream's getBuffer/returnBuffer work. The priv 61 * pointer may still be modified. 62 * 63 * STATE_PREPARING: The stream's buffers are being pre-allocated for use. On 64 * older HALs, this is done as part of configuration, but in newer HALs 65 * buffers may be allocated at time of first use. But some use cases require 66 * buffer allocation upfront, to minmize disruption due to lengthy allocation 67 * duration. In this state, only prepareNextBuffer() and cancelPrepare() 68 * may be called. 69 * 70 * Transition table: 71 * 72 * <none> => STATE_CONSTRUCTED: 73 * When constructed with valid arguments 74 * <none> => STATE_ERROR: 75 * When constructed with invalid arguments 76 * STATE_CONSTRUCTED => STATE_IN_CONFIG: 77 * When startConfiguration() is called 78 * STATE_IN_CONFIG => STATE_CONFIGURED: 79 * When finishConfiguration() is called 80 * STATE_IN_CONFIG => STATE_ERROR: 81 * When finishConfiguration() fails to allocate or register buffers. 82 * STATE_CONFIGURED => STATE_IN_RE_CONFIG: * 83 * When startConfiguration() is called again, after making sure stream is 84 * idle with waitUntilIdle(). 85 * STATE_IN_RE_CONFIG => STATE_CONFIGURED: 86 * When finishConfiguration() is called. 87 * STATE_IN_RE_CONFIG => STATE_ERROR: 88 * When finishConfiguration() fails to allocate or register buffers. 89 * STATE_CONFIGURED => STATE_CONSTRUCTED: 90 * When disconnect() is called after making sure stream is idle with 91 * waitUntilIdle(). 92 * STATE_CONFIGURED => STATE_PREPARING: 93 * When startPrepare is called before the stream has a buffer 94 * queued back into it for the first time. 95 * STATE_PREPARING => STATE_CONFIGURED: 96 * When sufficient prepareNextBuffer calls have been made to allocate 97 * all stream buffers, or cancelPrepare is called. 98 * 99 * Status Tracking: 100 * Each stream is tracked by StatusTracker as a separate component, 101 * depending on the handed out buffer count. The state must be STATE_CONFIGURED 102 * in order for the component to be marked. 103 * 104 * It's marked in one of two ways: 105 * 106 * - ACTIVE: One or more buffers have been handed out (with #getBuffer). 107 * - IDLE: All buffers have been returned (with #returnBuffer), and their 108 * respective release_fence(s) have been signaled. 109 * 110 * A typical use case is output streams. When the HAL has any buffers 111 * dequeued, the stream is marked ACTIVE. When the HAL returns all buffers 112 * (e.g. if no capture requests are active), the stream is marked IDLE. 113 * In this use case, the app consumer does not affect the component status. 114 * 115 */ 116class Camera3Stream : 117 protected camera3_stream, 118 public virtual Camera3StreamInterface, 119 public virtual RefBase { 120 public: 121 122 virtual ~Camera3Stream(); 123 124 static Camera3Stream* cast(camera3_stream *stream); 125 static const Camera3Stream* cast(const camera3_stream *stream); 126 127 /** 128 * Get the stream's ID 129 */ 130 int getId() const; 131 132 /** 133 * Get the output stream set id. 134 */ 135 int getStreamSetId() const; 136 137 /** 138 * Get the stream's dimensions and format 139 */ 140 uint32_t getWidth() const; 141 uint32_t getHeight() const; 142 int getFormat() const; 143 android_dataspace getDataSpace() const; 144 145 /** 146 * Start the stream configuration process. Returns a handle to the stream's 147 * information to be passed into the HAL device's configure_streams call. 148 * 149 * Until finishConfiguration() is called, no other methods on the stream may be 150 * called. The usage and max_buffers fields of camera3_stream may be modified 151 * between start/finishConfiguration, but may not be changed after that. 152 * The priv field of camera3_stream may be modified at any time after 153 * startConfiguration. 154 * 155 * Returns NULL in case of error starting configuration. 156 */ 157 camera3_stream* startConfiguration(); 158 159 /** 160 * Check if the stream is mid-configuration (start has been called, but not 161 * finish). Used for lazy completion of configuration. 162 */ 163 bool isConfiguring() const; 164 165 /** 166 * Completes the stream configuration process. During this call, the stream 167 * may call the device's register_stream_buffers() method. The stream 168 * information structure returned by startConfiguration() may no longer be 169 * modified after this call, but can still be read until the destruction of 170 * the stream. 171 * 172 * Returns: 173 * OK on a successful configuration 174 * NO_INIT in case of a serious error from the HAL device 175 * NO_MEMORY in case of an error registering buffers 176 * INVALID_OPERATION in case connecting to the consumer failed 177 */ 178 status_t finishConfiguration(camera3_device *hal3Device); 179 180 /** 181 * Cancels the stream configuration process. This returns the stream to the 182 * initial state, allowing it to be configured again later. 183 * This is done if the HAL rejects the proposed combined stream configuration 184 */ 185 status_t cancelConfiguration(); 186 187 /** 188 * Determine whether the stream has already become in-use (has received 189 * a valid filled buffer), which determines if a stream can still have 190 * prepareNextBuffer called on it. 191 */ 192 bool isUnpreparable(); 193 194 /** 195 * Start stream preparation. May only be called in the CONFIGURED state, 196 * when no valid buffers have yet been returned to this stream. Prepares 197 * up to maxCount buffers, or the maximum number of buffers needed by the 198 * pipeline if maxCount is ALLOCATE_PIPELINE_MAX. 199 * 200 * If no prepartion is necessary, returns OK and does not transition to 201 * PREPARING state. Otherwise, returns NOT_ENOUGH_DATA and transitions 202 * to PREPARING. 203 * 204 * This call performs no allocation, so is quick to call. 205 * 206 * Returns: 207 * OK if no more buffers need to be preallocated 208 * NOT_ENOUGH_DATA if calls to prepareNextBuffer are needed to finish 209 * buffer pre-allocation, and transitions to the PREPARING state. 210 * NO_INIT in case of a serious error from the HAL device 211 * INVALID_OPERATION if called when not in CONFIGURED state, or a 212 * valid buffer has already been returned to this stream. 213 */ 214 status_t startPrepare(int maxCount); 215 216 /** 217 * Check if the stream is mid-preparing. 218 */ 219 bool isPreparing() const; 220 221 /** 222 * Continue stream buffer preparation by allocating the next 223 * buffer for this stream. May only be called in the PREPARED state. 224 * 225 * Returns OK and transitions to the CONFIGURED state if all buffers 226 * are allocated after the call concludes. Otherwise returns NOT_ENOUGH_DATA. 227 * 228 * This call allocates one buffer, which may take several milliseconds for 229 * large buffers. 230 * 231 * Returns: 232 * OK if no more buffers need to be preallocated, and transitions 233 * to the CONFIGURED state. 234 * NOT_ENOUGH_DATA if more calls to prepareNextBuffer are needed to finish 235 * buffer pre-allocation. 236 * NO_INIT in case of a serious error from the HAL device 237 * INVALID_OPERATION if called when not in CONFIGURED state, or a 238 * valid buffer has already been returned to this stream. 239 */ 240 status_t prepareNextBuffer(); 241 242 /** 243 * Cancel stream preparation early. In case allocation needs to be 244 * stopped, this method transitions the stream back to the CONFIGURED state. 245 * Buffers that have been allocated with prepareNextBuffer remain that way, 246 * but a later use of prepareNextBuffer will require just as many 247 * calls as if the earlier prepare attempt had not existed. 248 * 249 * Returns: 250 * OK if cancellation succeeded, and transitions to the CONFIGURED state 251 * INVALID_OPERATION if not in the PREPARING state 252 * NO_INIT in case of a serious error from the HAL device 253 */ 254 status_t cancelPrepare(); 255 256 /** 257 * Tear down memory for this stream. This frees all unused gralloc buffers 258 * allocated for this stream, but leaves it ready for operation afterward. 259 * 260 * May only be called in the CONFIGURED state, and keeps the stream in 261 * the CONFIGURED state. 262 * 263 * Returns: 264 * OK if teardown succeeded. 265 * INVALID_OPERATION if not in the CONFIGURED state 266 * NO_INIT in case of a serious error from the HAL device 267 */ 268 status_t tearDown(); 269 270 /** 271 * Fill in the camera3_stream_buffer with the next valid buffer for this 272 * stream, to hand over to the HAL. 273 * 274 * This method may only be called once finishConfiguration has been called. 275 * For bidirectional streams, this method applies to the output-side 276 * buffers. 277 * 278 */ 279 status_t getBuffer(camera3_stream_buffer *buffer); 280 281 /** 282 * Return a buffer to the stream after use by the HAL. 283 * 284 * This method may only be called for buffers provided by getBuffer(). 285 * For bidirectional streams, this method applies to the output-side buffers 286 */ 287 status_t returnBuffer(const camera3_stream_buffer &buffer, 288 nsecs_t timestamp); 289 290 /** 291 * Fill in the camera3_stream_buffer with the next valid buffer for this 292 * stream, to hand over to the HAL. 293 * 294 * This method may only be called once finishConfiguration has been called. 295 * For bidirectional streams, this method applies to the input-side 296 * buffers. 297 * 298 */ 299 status_t getInputBuffer(camera3_stream_buffer *buffer); 300 301 /** 302 * Return a buffer to the stream after use by the HAL. 303 * 304 * This method may only be called for buffers provided by getBuffer(). 305 * For bidirectional streams, this method applies to the input-side buffers 306 */ 307 status_t returnInputBuffer(const camera3_stream_buffer &buffer); 308 309 // get the buffer producer of the input buffer queue. 310 // only apply to input streams. 311 status_t getInputBufferProducer(sp<IGraphicBufferProducer> *producer); 312 313 /** 314 * Whether any of the stream's buffers are currently in use by the HAL, 315 * including buffers that have been returned but not yet had their 316 * release fence signaled. 317 */ 318 bool hasOutstandingBuffers() const; 319 320 enum { 321 TIMEOUT_NEVER = -1 322 }; 323 324 /** 325 * Set the status tracker to notify about idle transitions 326 */ 327 virtual status_t setStatusTracker(sp<StatusTracker> statusTracker); 328 329 /** 330 * Disconnect stream from its non-HAL endpoint. After this, 331 * start/finishConfiguration must be called before the stream can be used 332 * again. This cannot be called if the stream has outstanding dequeued 333 * buffers. 334 */ 335 status_t disconnect(); 336 337 /** 338 * Debug dump of the stream's state. 339 */ 340 virtual void dump(int fd, const Vector<String16> &args) const = 0; 341 342 /** 343 * Add a camera3 buffer listener. Adding the same listener twice has 344 * no effect. 345 */ 346 void addBufferListener( 347 wp<Camera3StreamBufferListener> listener); 348 349 /** 350 * Remove a camera3 buffer listener. Removing the same listener twice 351 * or the listener that was never added has no effect. 352 */ 353 void removeBufferListener( 354 const sp<Camera3StreamBufferListener>& listener); 355 356 protected: 357 const int mId; 358 /** 359 * Stream set id, used to indicate which group of this stream belongs to for buffer sharing 360 * across multiple streams. 361 * 362 * The default value is set to CAMERA3_STREAM_SET_ID_INVALID, which indicates that this stream 363 * doesn't intend to share buffers with any other streams, and this stream will fall back to 364 * the existing BufferQueue mechanism to manage the buffer allocations and buffer circulation. 365 * When a valid stream set id is set, this stream intends to use the Camera3BufferManager to 366 * manage the buffer allocations; the BufferQueue will only handle the buffer transaction 367 * between the producer and consumer. For this case, upon successfully registration, the streams 368 * with the same stream set id will potentially share the buffers allocated by 369 * Camera3BufferManager. 370 */ 371 const int mSetId; 372 373 const String8 mName; 374 // Zero for formats with fixed buffer size for given dimensions. 375 const size_t mMaxSize; 376 377 enum { 378 STATE_ERROR, 379 STATE_CONSTRUCTED, 380 STATE_IN_CONFIG, 381 STATE_IN_RECONFIG, 382 STATE_CONFIGURED, 383 STATE_PREPARING 384 } mState; 385 386 mutable Mutex mLock; 387 388 Camera3Stream(int id, camera3_stream_type type, 389 uint32_t width, uint32_t height, size_t maxSize, int format, 390 android_dataspace dataSpace, camera3_stream_rotation_t rotation, 391 int setId); 392 393 /** 394 * Interface to be implemented by derived classes 395 */ 396 397 // getBuffer / returnBuffer implementations 398 399 // Since camera3_stream_buffer includes a raw pointer to the stream, 400 // cast to camera3_stream*, implementations must increment the 401 // refcount of the stream manually in getBufferLocked, and decrement it in 402 // returnBufferLocked. 403 virtual status_t getBufferLocked(camera3_stream_buffer *buffer); 404 virtual status_t returnBufferLocked(const camera3_stream_buffer &buffer, 405 nsecs_t timestamp); 406 virtual status_t getInputBufferLocked(camera3_stream_buffer *buffer); 407 virtual status_t returnInputBufferLocked( 408 const camera3_stream_buffer &buffer); 409 virtual bool hasOutstandingBuffersLocked() const = 0; 410 // Get the buffer producer of the input buffer queue. Only apply to input streams. 411 virtual status_t getInputBufferProducerLocked(sp<IGraphicBufferProducer> *producer); 412 413 // Can return -ENOTCONN when we are already disconnected (not an error) 414 virtual status_t disconnectLocked() = 0; 415 416 // Configure the buffer queue interface to the other end of the stream, 417 // after the HAL has provided usage and max_buffers values. After this call, 418 // the stream must be ready to produce all buffers for registration with 419 // HAL. 420 virtual status_t configureQueueLocked() = 0; 421 422 // Get the total number of buffers in the queue 423 virtual size_t getBufferCountLocked() = 0; 424 425 // Get handout output buffer count. 426 virtual size_t getHandoutOutputBufferCountLocked() = 0; 427 428 // Get handout input buffer count. 429 virtual size_t getHandoutInputBufferCountLocked() = 0; 430 431 // Get the usage flags for the other endpoint, or return 432 // INVALID_OPERATION if they cannot be obtained. 433 virtual status_t getEndpointUsage(uint32_t *usage) const = 0; 434 435 // Tracking for idle state 436 wp<StatusTracker> mStatusTracker; 437 // Status tracker component ID 438 int mStatusId; 439 440 // Tracking for stream prepare - whether this stream can still have 441 // prepareNextBuffer called on it. 442 bool mStreamUnpreparable; 443 444 private: 445 uint32_t mOldUsage; 446 uint32_t mOldMaxBuffers; 447 Condition mOutputBufferReturnedSignal; 448 Condition mInputBufferReturnedSignal; 449 static const nsecs_t kWaitForBufferDuration = 3000000000LL; // 3000 ms 450 451 // Gets all buffers from endpoint and registers them with the HAL. 452 status_t registerBuffersLocked(camera3_device *hal3Device); 453 454 void fireBufferListenersLocked(const camera3_stream_buffer& buffer, 455 bool acquired, bool output); 456 List<wp<Camera3StreamBufferListener> > mBufferListenerList; 457 458 status_t cancelPrepareLocked(); 459 460 // Return whether the buffer is in the list of outstanding buffers. 461 bool isOutstandingBuffer(const camera3_stream_buffer& buffer); 462 463 // Remove the buffer from the list of outstanding buffers. 464 void removeOutstandingBuffer(const camera3_stream_buffer& buffer); 465 466 // Tracking for PREPARING state 467 468 // State of buffer preallocation. Only true if either prepareNextBuffer 469 // has been called sufficient number of times, or stream configuration 470 // had to register buffers with the HAL 471 bool mPrepared; 472 473 Vector<camera3_stream_buffer_t> mPreparedBuffers; 474 size_t mPreparedBufferIdx; 475 476 // Number of buffers allocated on last prepare call. 477 size_t mLastMaxCount; 478 479 // Outstanding buffers dequeued from the stream's buffer queue. 480 List<buffer_handle_t> mOutstandingBuffers; 481 482}; // class Camera3Stream 483 484}; // namespace camera3 485 486}; // namespace android 487 488#endif 489