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 23 struct camera3_stream_buffer; 24 25 namespace android { 26 27 namespace camera3 { 28 29 class StatusTracker; 30 31 /** 32 * An interface for managing a single stream of input and/or output data from 33 * the camera device. 34 */ 35 class 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 * Tear down memory for this stream. This frees all unused gralloc buffers 156 * allocated for this stream, but leaves it ready for operation afterward. 157 * 158 * May only be called in the CONFIGURED state, and keeps the stream in 159 * the CONFIGURED state. 160 * 161 * Returns: 162 * OK if teardown succeeded. 163 * INVALID_OPERATION if not in the CONFIGURED state 164 * NO_INIT in case of a serious error from the HAL device 165 */ 166 virtual status_t tearDown() = 0; 167 168 /** 169 * Fill in the camera3_stream_buffer with the next valid buffer for this 170 * stream, to hand over to the HAL. 171 * 172 * This method may only be called once finishConfiguration has been called. 173 * For bidirectional streams, this method applies to the output-side 174 * buffers. 175 * 176 */ 177 virtual status_t getBuffer(camera3_stream_buffer *buffer) = 0; 178 179 /** 180 * Return a buffer to the stream after use by the HAL. 181 * 182 * This method may only be called for buffers provided by getBuffer(). 183 * For bidirectional streams, this method applies to the output-side buffers 184 */ 185 virtual status_t returnBuffer(const camera3_stream_buffer &buffer, 186 nsecs_t timestamp) = 0; 187 188 /** 189 * Fill in the camera3_stream_buffer with the next valid buffer for this 190 * stream, to hand over to the HAL. 191 * 192 * This method may only be called once finishConfiguration has been called. 193 * For bidirectional streams, this method applies to the input-side 194 * buffers. 195 * 196 */ 197 virtual status_t getInputBuffer(camera3_stream_buffer *buffer) = 0; 198 199 /** 200 * Return a buffer to the stream after use by the HAL. 201 * 202 * This method may only be called for buffers provided by getBuffer(). 203 * For bidirectional streams, this method applies to the input-side buffers 204 */ 205 virtual status_t returnInputBuffer(const camera3_stream_buffer &buffer) = 0; 206 207 /** 208 * Get the buffer producer of the input buffer queue. 209 * 210 * This method only applies to input streams. 211 */ 212 virtual status_t getInputBufferProducer(sp<IGraphicBufferProducer> *producer) = 0; 213 214 /** 215 * Whether any of the stream's buffers are currently in use by the HAL, 216 * including buffers that have been returned but not yet had their 217 * release fence signaled. 218 */ 219 virtual bool hasOutstandingBuffers() const = 0; 220 221 enum { 222 TIMEOUT_NEVER = -1 223 }; 224 225 /** 226 * Set the state tracker to use for signaling idle transitions. 227 */ 228 virtual status_t setStatusTracker(sp<StatusTracker> statusTracker) = 0; 229 230 /** 231 * Disconnect stream from its non-HAL endpoint. After this, 232 * start/finishConfiguration must be called before the stream can be used 233 * again. This cannot be called if the stream has outstanding dequeued 234 * buffers. 235 */ 236 virtual status_t disconnect() = 0; 237 238 /** 239 * Debug dump of the stream's state. 240 */ 241 virtual void dump(int fd, const Vector<String16> &args) const = 0; 242 243 virtual void addBufferListener( 244 wp<Camera3StreamBufferListener> listener) = 0; 245 virtual void removeBufferListener( 246 const sp<Camera3StreamBufferListener>& listener) = 0; 247 }; 248 249 } // namespace camera3 250 251 } // namespace android 252 253 #endif 254