Camera3StreamInterface.h revision d46a6b9fd8b2a4f9098757384711e2cd03a91651
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_INTERFACE_H 18#define ANDROID_SERVERS_CAMERA3_STREAM_INTERFACE_H 19 20#include <utils/RefBase.h> 21#include "Camera3StreamBufferListener.h" 22 23struct camera3_stream_buffer; 24 25namespace android { 26 27namespace camera3 { 28 29class StatusTracker; 30 31/** 32 * An interface for managing a single stream of input and/or output data from 33 * the camera device. 34 */ 35class Camera3StreamInterface : public virtual RefBase { 36 public: 37 /** 38 * Get the stream's ID 39 */ 40 virtual int getId() const = 0; 41 42 /** 43 * Get the stream's dimensions and format 44 */ 45 virtual uint32_t getWidth() const = 0; 46 virtual uint32_t getHeight() const = 0; 47 virtual int getFormat() const = 0; 48 virtual android_dataspace getDataSpace() const = 0; 49 50 /** 51 * Start the stream configuration process. Returns a handle to the stream's 52 * information to be passed into the HAL device's configure_streams call. 53 * 54 * Until finishConfiguration() is called, no other methods on the stream may 55 * be called. The usage and max_buffers fields of camera3_stream may be 56 * modified between start/finishConfiguration, but may not be changed after 57 * that. The priv field of camera3_stream may be modified at any time after 58 * startConfiguration. 59 * 60 * Returns NULL in case of error starting configuration. 61 */ 62 virtual camera3_stream* startConfiguration() = 0; 63 64 /** 65 * Check if the stream is mid-configuration (start has been called, but not 66 * finish). Used for lazy completion of configuration. 67 */ 68 virtual bool isConfiguring() const = 0; 69 70 /** 71 * Completes the stream configuration process. During this call, the stream 72 * may call the device's register_stream_buffers() method. The stream 73 * information structure returned by startConfiguration() may no longer be 74 * modified after this call, but can still be read until the destruction of 75 * the stream. 76 * 77 * Returns: 78 * OK on a successful configuration 79 * NO_INIT in case of a serious error from the HAL device 80 * NO_MEMORY in case of an error registering buffers 81 * INVALID_OPERATION in case connecting to the consumer failed 82 */ 83 virtual status_t finishConfiguration(camera3_device *hal3Device) = 0; 84 85 /** 86 * Cancels the stream configuration process. This returns the stream to the 87 * initial state, allowing it to be configured again later. 88 * This is done if the HAL rejects the proposed combined stream configuration 89 */ 90 virtual status_t cancelConfiguration() = 0; 91 92 /** 93 * Determine whether the stream has already become in-use (has received 94 * a valid filled buffer), which determines if a stream can still have 95 * prepareNextBuffer called on it. 96 */ 97 virtual bool isUnpreparable() = 0; 98 99 /** 100 * Start stream preparation. May only be called in the CONFIGURED state, 101 * when no valid buffers have yet been returned to this stream. 102 * 103 * If no prepartion is necessary, returns OK and does not transition to 104 * PREPARING state. Otherwise, returns NOT_ENOUGH_DATA and transitions 105 * to PREPARING. 106 * 107 * Returns: 108 * OK if no more buffers need to be preallocated 109 * NOT_ENOUGH_DATA if calls to prepareNextBuffer are needed to finish 110 * buffer pre-allocation, and transitions to the PREPARING state. 111 * NO_INIT in case of a serious error from the HAL device 112 * INVALID_OPERATION if called when not in CONFIGURED state, or a 113 * valid buffer has already been returned to this stream. 114 */ 115 virtual status_t startPrepare() = 0; 116 117 /** 118 * Check if the stream is mid-preparing. 119 */ 120 virtual bool isPreparing() const = 0; 121 122 /** 123 * Continue stream buffer preparation by allocating the next 124 * buffer for this stream. May only be called in the PREPARED state. 125 * 126 * Returns OK and transitions to the CONFIGURED state if all buffers 127 * are allocated after the call concludes. Otherwise returns NOT_ENOUGH_DATA. 128 * 129 * Returns: 130 * OK if no more buffers need to be preallocated, and transitions 131 * to the CONFIGURED state. 132 * NOT_ENOUGH_DATA if more calls to prepareNextBuffer are needed to finish 133 * buffer pre-allocation. 134 * NO_INIT in case of a serious error from the HAL device 135 * INVALID_OPERATION if called when not in CONFIGURED state, or a 136 * valid buffer has already been returned to this stream. 137 */ 138 virtual status_t prepareNextBuffer() = 0; 139 140 /** 141 * Cancel stream preparation early. In case allocation needs to be 142 * stopped, this method transitions the stream back to the CONFIGURED state. 143 * Buffers that have been allocated with prepareNextBuffer remain that way, 144 * but a later use of prepareNextBuffer will require just as many 145 * calls as if the earlier prepare attempt had not existed. 146 * 147 * Returns: 148 * OK if cancellation succeeded, and transitions to the CONFIGURED state 149 * INVALID_OPERATION if not in the PREPARING state 150 * NO_INIT in case of a serious error from the HAL device 151 */ 152 virtual status_t cancelPrepare() = 0; 153 154 /** 155 * Fill in the camera3_stream_buffer with the next valid buffer for this 156 * stream, to hand over to the HAL. 157 * 158 * This method may only be called once finishConfiguration has been called. 159 * For bidirectional streams, this method applies to the output-side 160 * buffers. 161 * 162 */ 163 virtual status_t getBuffer(camera3_stream_buffer *buffer) = 0; 164 165 /** 166 * Return a buffer to the stream after use by the HAL. 167 * 168 * This method may only be called for buffers provided by getBuffer(). 169 * For bidirectional streams, this method applies to the output-side buffers 170 */ 171 virtual status_t returnBuffer(const camera3_stream_buffer &buffer, 172 nsecs_t timestamp) = 0; 173 174 /** 175 * Fill in the camera3_stream_buffer with the next valid buffer for this 176 * stream, to hand over to the HAL. 177 * 178 * This method may only be called once finishConfiguration has been called. 179 * For bidirectional streams, this method applies to the input-side 180 * buffers. 181 * 182 */ 183 virtual status_t getInputBuffer(camera3_stream_buffer *buffer) = 0; 184 185 /** 186 * Return a buffer to the stream after use by the HAL. 187 * 188 * This method may only be called for buffers provided by getBuffer(). 189 * For bidirectional streams, this method applies to the input-side buffers 190 */ 191 virtual status_t returnInputBuffer(const camera3_stream_buffer &buffer) = 0; 192 193 /** 194 * Get the buffer producer of the input buffer queue. 195 * 196 * This method only applies to input streams. 197 */ 198 virtual status_t getInputBufferProducer(sp<IGraphicBufferProducer> *producer) = 0; 199 200 /** 201 * Whether any of the stream's buffers are currently in use by the HAL, 202 * including buffers that have been returned but not yet had their 203 * release fence signaled. 204 */ 205 virtual bool hasOutstandingBuffers() const = 0; 206 207 enum { 208 TIMEOUT_NEVER = -1 209 }; 210 211 /** 212 * Set the state tracker to use for signaling idle transitions. 213 */ 214 virtual status_t setStatusTracker(sp<StatusTracker> statusTracker) = 0; 215 216 /** 217 * Disconnect stream from its non-HAL endpoint. After this, 218 * start/finishConfiguration must be called before the stream can be used 219 * again. This cannot be called if the stream has outstanding dequeued 220 * buffers. 221 */ 222 virtual status_t disconnect() = 0; 223 224 /** 225 * Debug dump of the stream's state. 226 */ 227 virtual void dump(int fd, const Vector<String16> &args) const = 0; 228 229 virtual void addBufferListener( 230 wp<Camera3StreamBufferListener> listener) = 0; 231 virtual void removeBufferListener( 232 const sp<Camera3StreamBufferListener>& listener) = 0; 233}; 234 235} // namespace camera3 236 237} // namespace android 238 239#endif 240