blob: 805df825992bc67371a2cf8ed6a8c4968875ed31 [file] [log] [blame]
/*
* Copyright (C) 2013-2018 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.
*/
#ifndef ANDROID_SERVERS_CAMERA3_STREAM_H
#define ANDROID_SERVERS_CAMERA3_STREAM_H
#include <gui/Surface.h>
#include <utils/RefBase.h>
#include <utils/String8.h>
#include <utils/String16.h>
#include <utils/List.h>
#include "hardware/camera3.h"
#include "utils/LatencyHistogram.h"
#include "Camera3StreamBufferListener.h"
#include "Camera3StreamInterface.h"
namespace android {
namespace camera3 {
/**
* A class for managing a single stream of input or output data from the camera
* device.
*
* The stream has an internal state machine to track whether it's
* connected/configured/etc.
*
* States:
*
* STATE_ERROR: A serious error has occurred, stream is unusable. Outstanding
* buffers may still be returned.
*
* STATE_CONSTRUCTED: The stream is ready for configuration, but buffers cannot
* be gotten yet. Not connected to any endpoint, no buffers are registered
* with the HAL.
*
* STATE_IN_CONFIG: Configuration has started, but not yet concluded. During this
* time, the usage, max_buffers, and priv fields of camera3_stream returned by
* startConfiguration() may be modified.
*
* STATE_IN_RE_CONFIG: Configuration has started, and the stream has been
* configured before. Need to track separately from IN_CONFIG to avoid
* re-registering buffers with HAL.
*
* STATE_CONFIGURED: Stream is configured, and has registered buffers with the
* HAL (if necessary). The stream's getBuffer/returnBuffer work. The priv
* pointer may still be modified.
*
* STATE_PREPARING: The stream's buffers are being pre-allocated for use. On
* older HALs, this is done as part of configuration, but in newer HALs
* buffers may be allocated at time of first use. But some use cases require
* buffer allocation upfront, to minmize disruption due to lengthy allocation
* duration. In this state, only prepareNextBuffer() and cancelPrepare()
* may be called.
*
* STATE_IN_IDLE: This is a temporary state only intended to be used for input
* streams and only for the case where we need to re-configure the camera device
* while the input stream has an outstanding buffer. All other streams should not
* be able to switch to this state. For them this is invalid and should be handled
* as an unknown state.
*
* Transition table:
*
* <none> => STATE_CONSTRUCTED:
* When constructed with valid arguments
* <none> => STATE_ERROR:
* When constructed with invalid arguments
* STATE_CONSTRUCTED => STATE_IN_CONFIG:
* When startConfiguration() is called
* STATE_IN_CONFIG => STATE_CONFIGURED:
* When finishConfiguration() is called
* STATE_IN_CONFIG => STATE_ERROR:
* When finishConfiguration() fails to allocate or register buffers.
* STATE_CONFIGURED => STATE_IN_RE_CONFIG: *
* When startConfiguration() is called again, after making sure stream is
* idle with waitUntilIdle().
* STATE_IN_RE_CONFIG => STATE_CONFIGURED:
* When finishConfiguration() is called.
* STATE_IN_RE_CONFIG => STATE_ERROR:
* When finishConfiguration() fails to allocate or register buffers.
* STATE_CONFIGURED => STATE_CONSTRUCTED:
* When disconnect() is called after making sure stream is idle with
* waitUntilIdle().
* STATE_CONFIGURED => STATE_PREPARING:
* When startPrepare is called before the stream has a buffer
* queued back into it for the first time.
* STATE_PREPARING => STATE_CONFIGURED:
* When sufficient prepareNextBuffer calls have been made to allocate
* all stream buffers, or cancelPrepare is called.
* STATE_CONFIGURED => STATE_ABANDONED:
* When the buffer queue of the stream is abandoned.
* STATE_CONFIGURED => STATE_IN_IDLE:
* Only for an input stream which has an outstanding buffer.
* STATE_IN_IDLE => STATE_CONFIGURED:
* After the internal re-configuration, the input should revert back to
* the configured state.
*
* Status Tracking:
* Each stream is tracked by StatusTracker as a separate component,
* depending on the handed out buffer count. The state must be STATE_CONFIGURED
* in order for the component to be marked.
*
* It's marked in one of two ways:
*
* - ACTIVE: One or more buffers have been handed out (with #getBuffer).
* - IDLE: All buffers have been returned (with #returnBuffer), and their
* respective release_fence(s) have been signaled. The only exception to this
* rule is an input stream that moves to "STATE_IN_IDLE" during internal
* re-configuration.
*
* A typical use case is output streams. When the HAL has any buffers
* dequeued, the stream is marked ACTIVE. When the HAL returns all buffers
* (e.g. if no capture requests are active), the stream is marked IDLE.
* In this use case, the app consumer does not affect the component status.
*
*/
class Camera3Stream :
protected camera3_stream,
public virtual Camera3StreamInterface,
public virtual RefBase {
public:
virtual ~Camera3Stream();
static Camera3Stream* cast(camera3_stream *stream);
static const Camera3Stream* cast(const camera3_stream *stream);
/**
* Get the stream's ID
*/
int getId() const;
/**
* Get the output stream set id.
*/
int getStreamSetId() const;
/**
* Get the stream's dimensions and format
*/
uint32_t getWidth() const;
uint32_t getHeight() const;
int getFormat() const;
android_dataspace getDataSpace() const;
uint64_t getUsage() const;
void setUsage(uint64_t usage);
void setFormatOverride(bool formatOverriden);
bool isFormatOverridden() const;
int getOriginalFormat() const;
void setDataSpaceOverride(bool dataSpaceOverriden);
bool isDataSpaceOverridden() const;
android_dataspace getOriginalDataSpace() const;
const String8& physicalCameraId() const;
camera3_stream* asHalStream() override {
return this;
}
/**
* Start the stream configuration process. Returns a handle to the stream's
* information to be passed into the HAL device's configure_streams call.
*
* Until finishConfiguration() is called, no other methods on the stream may be
* called. The usage and max_buffers fields of camera3_stream may be modified
* between start/finishConfiguration, but may not be changed after that.
* The priv field of camera3_stream may be modified at any time after
* startConfiguration.
*
* Returns NULL in case of error starting configuration.
*/
camera3_stream* startConfiguration();
/**
* Check if the stream is mid-configuration (start has been called, but not
* finish). Used for lazy completion of configuration.
*/
bool isConfiguring() const;
/**
* Completes the stream configuration process. The stream information
* structure returned by startConfiguration() may no longer be modified
* after this call, but can still be read until the destruction of the
* stream.
*
* streamReconfigured: set to true when a stream is being reconfigured.
*
* Returns:
* OK on a successful configuration
* NO_INIT in case of a serious error from the HAL device
* NO_MEMORY in case of an error registering buffers
* INVALID_OPERATION in case connecting to the consumer failed or consumer
* doesn't exist yet.
*/
status_t finishConfiguration(/*out*/bool* streamReconfigured = nullptr);
/**
* Cancels the stream configuration process. This returns the stream to the
* initial state, allowing it to be configured again later.
* This is done if the HAL rejects the proposed combined stream configuration
*/
status_t cancelConfiguration();
/**
* Determine whether the stream has already become in-use (has received
* a valid filled buffer), which determines if a stream can still have
* prepareNextBuffer called on it.
*/
bool isUnpreparable();
/**
* Start stream preparation. May only be called in the CONFIGURED state,
* when no valid buffers have yet been returned to this stream. Prepares
* up to maxCount buffers, or the maximum number of buffers needed by the
* pipeline if maxCount is ALLOCATE_PIPELINE_MAX.
*
* If no prepartion is necessary, returns OK and does not transition to
* PREPARING state. Otherwise, returns NOT_ENOUGH_DATA and transitions
* to PREPARING.
*
* This call performs no allocation, so is quick to call.
*
* blockRequest specifies whether prepare will block upcoming capture
* request. This flag should only be set to false if the caller guarantees
* the whole buffer preparation process is done before capture request
* comes in.
*
* Returns:
* OK if no more buffers need to be preallocated
* NOT_ENOUGH_DATA if calls to prepareNextBuffer are needed to finish
* buffer pre-allocation, and transitions to the PREPARING state.
* NO_INIT in case of a serious error from the HAL device
* INVALID_OPERATION if called when not in CONFIGURED state, or a
* valid buffer has already been returned to this stream.
*/
status_t startPrepare(int maxCount, bool blockRequest);
/**
* Check if the request on a stream is blocked by prepare.
*/
bool isBlockedByPrepare() const;
/**
* Continue stream buffer preparation by allocating the next
* buffer for this stream. May only be called in the PREPARED state.
*
* Returns OK and transitions to the CONFIGURED state if all buffers
* are allocated after the call concludes. Otherwise returns NOT_ENOUGH_DATA.
*
* This call allocates one buffer, which may take several milliseconds for
* large buffers.
*
* Returns:
* OK if no more buffers need to be preallocated, and transitions
* to the CONFIGURED state.
* NOT_ENOUGH_DATA if more calls to prepareNextBuffer are needed to finish
* buffer pre-allocation.
* NO_INIT in case of a serious error from the HAL device
* INVALID_OPERATION if called when not in CONFIGURED state, or a
* valid buffer has already been returned to this stream.
*/
status_t prepareNextBuffer();
/**
* Cancel stream preparation early. In case allocation needs to be
* stopped, this method transitions the stream back to the CONFIGURED state.
* Buffers that have been allocated with prepareNextBuffer remain that way,
* but a later use of prepareNextBuffer will require just as many
* calls as if the earlier prepare attempt had not existed.
*
* Returns:
* OK if cancellation succeeded, and transitions to the CONFIGURED state
* INVALID_OPERATION if not in the PREPARING state
* NO_INIT in case of a serious error from the HAL device
*/
status_t cancelPrepare();
/**
* Tear down memory for this stream. This frees all unused gralloc buffers
* allocated for this stream, but leaves it ready for operation afterward.
*
* May only be called in the CONFIGURED state, and keeps the stream in
* the CONFIGURED state.
*
* Returns:
* OK if teardown succeeded.
* INVALID_OPERATION if not in the CONFIGURED state
* NO_INIT in case of a serious error from the HAL device
*/
status_t tearDown();
/**
* Fill in the camera3_stream_buffer with the next valid buffer for this
* stream, to hand over to the HAL.
*
* Multiple surfaces could share the same HAL stream, but a request may
* be only for a subset of surfaces. In this case, the
* Camera3StreamInterface object needs the surface ID information to acquire
* buffers for those surfaces.
*
* This method may only be called once finishConfiguration has been called.
* For bidirectional streams, this method applies to the output-side
* buffers.
*
*/
status_t getBuffer(camera3_stream_buffer *buffer,
nsecs_t waitBufferTimeout,
const std::vector<size_t>& surface_ids = std::vector<size_t>());
/**
* Return a buffer to the stream after use by the HAL.
*
* Multiple surfaces could share the same HAL stream, but a request may
* be only for a subset of surfaces. In this case, the
* Camera3StreamInterface object needs the surface ID information to attach
* buffers for those surfaces.
*
* This method may only be called for buffers provided by getBuffer().
* For bidirectional streams, this method applies to the output-side buffers
*/
status_t returnBuffer(const camera3_stream_buffer &buffer,
nsecs_t timestamp, bool timestampIncreasing,
const std::vector<size_t>& surface_ids = std::vector<size_t>(),
uint64_t frameNumber = 0);
/**
* Fill in the camera3_stream_buffer with the next valid buffer for this
* stream, to hand over to the HAL.
*
* This method may only be called once finishConfiguration has been called.
* For bidirectional streams, this method applies to the input-side
* buffers.
*
* Normally this call will block until the handed out buffer count is less than the stream
* max buffer count; if respectHalLimit is set to false, this is ignored.
*/
status_t getInputBuffer(camera3_stream_buffer *buffer, bool respectHalLimit = true);
/**
* Return a buffer to the stream after use by the HAL.
*
* This method may only be called for buffers provided by getBuffer().
* For bidirectional streams, this method applies to the input-side buffers
*/
status_t returnInputBuffer(const camera3_stream_buffer &buffer);
// get the buffer producer of the input buffer queue.
// only apply to input streams.
status_t getInputBufferProducer(sp<IGraphicBufferProducer> *producer);
/**
* Whether any of the stream's buffers are currently in use by the HAL,
* including buffers that have been returned but not yet had their
* release fence signaled.
*/
bool hasOutstandingBuffers() const;
/**
* Get number of buffers currently handed out to HAL
*/
size_t getOutstandingBuffersCount() const;
enum {
TIMEOUT_NEVER = -1
};
/**
* Set the status tracker to notify about idle transitions
*/
virtual status_t setStatusTracker(sp<StatusTracker> statusTracker);
/**
* Disconnect stream from its non-HAL endpoint. After this,
* start/finishConfiguration must be called before the stream can be used
* again. This cannot be called if the stream has outstanding dequeued
* buffers.
*/
status_t disconnect();
/**
* Debug dump of the stream's state.
*/
virtual void dump(int fd, const Vector<String16> &args) const;
/**
* Add a camera3 buffer listener. Adding the same listener twice has
* no effect.
*/
void addBufferListener(
wp<Camera3StreamBufferListener> listener);
/**
* Remove a camera3 buffer listener. Removing the same listener twice
* or the listener that was never added has no effect.
*/
void removeBufferListener(
const sp<Camera3StreamBufferListener>& listener);
// Setting listener will remove previous listener (if exists)
virtual void setBufferFreedListener(
wp<Camera3StreamBufferFreedListener> listener) override;
/**
* Return if the buffer queue of the stream is abandoned.
*/
bool isAbandoned() const;
/**
* Switch a configured stream with possibly outstanding buffers in idle
* state. Configuration for such streams will be skipped assuming there
* are no changes to the stream parameters.
*/
status_t forceToIdle();
/**
* Restore a forced idle stream to configured state, marking it active
* in case it contains outstanding buffers.
*/
status_t restoreConfiguredState();
/**
* Notify buffer stream listeners about incoming request with particular frame number.
*/
void fireBufferRequestForFrameNumber(uint64_t frameNumber,
const CameraMetadata& settings) override;
protected:
const int mId;
/**
* Stream set id, used to indicate which group of this stream belongs to for buffer sharing
* across multiple streams.
*
* The default value is set to CAMERA3_STREAM_SET_ID_INVALID, which indicates that this stream
* doesn't intend to share buffers with any other streams, and this stream will fall back to
* the existing BufferQueue mechanism to manage the buffer allocations and buffer circulation.
* When a valid stream set id is set, this stream intends to use the Camera3BufferManager to
* manage the buffer allocations; the BufferQueue will only handle the buffer transaction
* between the producer and consumer. For this case, upon successfully registration, the streams
* with the same stream set id will potentially share the buffers allocated by
* Camera3BufferManager.
*/
const int mSetId;
const String8 mName;
// Zero for formats with fixed buffer size for given dimensions.
const size_t mMaxSize;
enum StreamState {
STATE_ERROR,
STATE_CONSTRUCTED,
STATE_IN_CONFIG,
STATE_IN_RECONFIG,
STATE_CONFIGURED,
STATE_PREPARING,
STATE_ABANDONED,
STATE_IN_IDLE
} mState;
mutable Mutex mLock;
Camera3Stream(int id, camera3_stream_type type,
uint32_t width, uint32_t height, size_t maxSize, int format,
android_dataspace dataSpace, camera3_stream_rotation_t rotation,
const String8& physicalCameraId, int setId);
wp<Camera3StreamBufferFreedListener> mBufferFreedListener;
/**
* Interface to be implemented by derived classes
*/
// getBuffer / returnBuffer implementations
// Since camera3_stream_buffer includes a raw pointer to the stream,
// cast to camera3_stream*, implementations must increment the
// refcount of the stream manually in getBufferLocked, and decrement it in
// returnBufferLocked.
virtual status_t getBufferLocked(camera3_stream_buffer *buffer,
const std::vector<size_t>& surface_ids = std::vector<size_t>());
virtual status_t returnBufferLocked(const camera3_stream_buffer &buffer,
nsecs_t timestamp,
const std::vector<size_t>& surface_ids = std::vector<size_t>());
virtual status_t getInputBufferLocked(camera3_stream_buffer *buffer);
virtual status_t returnInputBufferLocked(
const camera3_stream_buffer &buffer);
virtual bool hasOutstandingBuffersLocked() const = 0;
// Get the buffer producer of the input buffer queue. Only apply to input streams.
virtual status_t getInputBufferProducerLocked(sp<IGraphicBufferProducer> *producer);
// Can return -ENOTCONN when we are already disconnected (not an error)
virtual status_t disconnectLocked() = 0;
// Configure the buffer queue interface to the other end of the stream,
// after the HAL has provided usage and max_buffers values. After this call,
// the stream must be ready to produce all buffers for registration with
// HAL.
// Returns NO_INIT or DEAD_OBJECT if the queue has been abandoned.
virtual status_t configureQueueLocked() = 0;
// Get the total number of buffers in the queue
virtual size_t getBufferCountLocked() = 0;
// Get handout output buffer count.
virtual size_t getHandoutOutputBufferCountLocked() const = 0;
// Get handout input buffer count.
virtual size_t getHandoutInputBufferCountLocked() = 0;
// Get the usage flags for the other endpoint, or return
// INVALID_OPERATION if they cannot be obtained.
virtual status_t getEndpointUsage(uint64_t *usage) const = 0;
// Return whether the buffer is in the list of outstanding buffers.
bool isOutstandingBuffer(const camera3_stream_buffer& buffer) const;
// Tracking for idle state
wp<StatusTracker> mStatusTracker;
// Status tracker component ID
int mStatusId;
// Tracking for stream prepare - whether this stream can still have
// prepareNextBuffer called on it.
bool mStreamUnpreparable;
uint64_t mUsage;
private:
// Previously configured stream properties (post HAL override)
uint64_t mOldUsage;
uint32_t mOldMaxBuffers;
int mOldFormat;
android_dataspace mOldDataSpace;
Condition mOutputBufferReturnedSignal;
Condition mInputBufferReturnedSignal;
static const nsecs_t kWaitForBufferDuration = 3000000000LL; // 3000 ms
void fireBufferListenersLocked(const camera3_stream_buffer& buffer,
bool acquired, bool output, nsecs_t timestamp = 0, uint64_t frameNumber = 0);
List<wp<Camera3StreamBufferListener> > mBufferListenerList;
status_t cancelPrepareLocked();
// Remove the buffer from the list of outstanding buffers.
void removeOutstandingBuffer(const camera3_stream_buffer& buffer);
// Tracking for PREPARING state
// State of buffer preallocation. Only true if either prepareNextBuffer
// has been called sufficient number of times, or stream configuration
// had to register buffers with the HAL
bool mPrepared;
bool mPrepareBlockRequest;
Vector<camera3_stream_buffer_t> mPreparedBuffers;
size_t mPreparedBufferIdx;
// Number of buffers allocated on last prepare call.
size_t mLastMaxCount;
mutable Mutex mOutstandingBuffersLock;
// Outstanding buffers dequeued from the stream's buffer queue.
List<buffer_handle_t> mOutstandingBuffers;
// Latency histogram of the wait time for handout buffer count to drop below
// max_buffers.
static const int32_t kBufferLimitLatencyBinSize = 33; //in ms
CameraLatencyHistogram mBufferLimitLatency;
//Keep track of original format when the stream is created in case it gets overridden
bool mFormatOverridden;
const int mOriginalFormat;
//Keep track of original dataSpace in case it gets overridden
bool mDataSpaceOverridden;
const android_dataspace mOriginalDataSpace;
String8 mPhysicalCameraId;
nsecs_t mLastTimestamp;
}; // class Camera3Stream
}; // namespace camera3
}; // namespace android
#endif