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#include "Camera3StreamBufferFreedListener.h"
23
24struct camera3_stream_buffer;
25
26namespace android {
27
28namespace camera3 {
29
30enum {
31    /**
32     * This stream set ID indicates that the set ID is invalid, and this stream doesn't intend to
33     * share buffers with any other stream. It is illegal to register this kind of stream to
34     * Camera3BufferManager.
35     */
36    CAMERA3_STREAM_SET_ID_INVALID = -1,
37
38    /**
39     * Invalid output stream ID.
40     */
41    CAMERA3_STREAM_ID_INVALID = -1,
42};
43
44class StatusTracker;
45
46// OutputStreamInfo describes the property of a camera stream.
47class OutputStreamInfo {
48    public:
49        int width;
50        int height;
51        int format;
52        android_dataspace dataSpace;
53        uint64_t consumerUsage;
54        bool finalized = false;
55        OutputStreamInfo() :
56            width(-1), height(-1), format(-1), dataSpace(HAL_DATASPACE_UNKNOWN),
57            consumerUsage(0) {}
58        OutputStreamInfo(int _width, int _height, int _format, android_dataspace _dataSpace,
59                uint64_t _consumerUsage) :
60            width(_width), height(_height), format(_format),
61            dataSpace(_dataSpace), consumerUsage(_consumerUsage) {}
62};
63
64/**
65 * An interface for managing a single stream of input and/or output data from
66 * the camera device.
67 */
68class Camera3StreamInterface : public virtual RefBase {
69  public:
70
71    enum {
72        ALLOCATE_PIPELINE_MAX = 0, // Allocate max buffers used by a given surface
73    };
74
75    /**
76     * Get the stream's ID
77     */
78    virtual int      getId() const = 0;
79
80    /**
81     * Get the output stream set id.
82     */
83    virtual int      getStreamSetId() const = 0;
84
85    /**
86     * Get the stream's dimensions and format
87     */
88    virtual uint32_t getWidth() const = 0;
89    virtual uint32_t getHeight() const = 0;
90    virtual int      getFormat() const = 0;
91    virtual android_dataspace getDataSpace() const = 0;
92    virtual void setFormatOverride(bool formatOverriden) = 0;
93    virtual bool isFormatOverridden() const = 0;
94    virtual int getOriginalFormat() const = 0;
95    virtual void setDataSpaceOverride(bool dataSpaceOverriden) = 0;
96    virtual bool isDataSpaceOverridden() const = 0;
97    virtual android_dataspace getOriginalDataSpace() const = 0;
98
99    /**
100     * Get a HAL3 handle for the stream, without starting stream configuration.
101     */
102    virtual camera3_stream* asHalStream() = 0;
103
104    /**
105     * Start the stream configuration process. Returns a handle to the stream's
106     * information to be passed into the HAL device's configure_streams call.
107     *
108     * Until finishConfiguration() is called, no other methods on the stream may
109     * be called. The usage and max_buffers fields of camera3_stream may be
110     * modified between start/finishConfiguration, but may not be changed after
111     * that. The priv field of camera3_stream may be modified at any time after
112     * startConfiguration.
113     *
114     * Returns NULL in case of error starting configuration.
115     */
116    virtual camera3_stream* startConfiguration() = 0;
117
118    /**
119     * Check if the stream is mid-configuration (start has been called, but not
120     * finish).  Used for lazy completion of configuration.
121     */
122    virtual bool    isConfiguring() const = 0;
123
124    /**
125     * Completes the stream configuration process. During this call, the stream
126     * may call the device's register_stream_buffers() method. The stream
127     * information structure returned by startConfiguration() may no longer be
128     * modified after this call, but can still be read until the destruction of
129     * the stream.
130     *
131     * Returns:
132     *   OK on a successful configuration
133     *   NO_INIT in case of a serious error from the HAL device
134     *   NO_MEMORY in case of an error registering buffers
135     *   INVALID_OPERATION in case connecting to the consumer failed
136     */
137    virtual status_t finishConfiguration() = 0;
138
139    /**
140     * Cancels the stream configuration process. This returns the stream to the
141     * initial state, allowing it to be configured again later.
142     * This is done if the HAL rejects the proposed combined stream configuration
143     */
144    virtual status_t cancelConfiguration() = 0;
145
146    /**
147     * Determine whether the stream has already become in-use (has received
148     * a valid filled buffer), which determines if a stream can still have
149     * prepareNextBuffer called on it.
150     */
151    virtual bool     isUnpreparable() = 0;
152
153    /**
154     * Start stream preparation. May only be called in the CONFIGURED state,
155     * when no valid buffers have yet been returned to this stream. Prepares
156     * up to maxCount buffers, or the maximum number of buffers needed by the
157     * pipeline if maxCount is ALLOCATE_PIPELINE_MAX.
158     *
159     * If no prepartion is necessary, returns OK and does not transition to
160     * PREPARING state. Otherwise, returns NOT_ENOUGH_DATA and transitions
161     * to PREPARING.
162     *
163     * Returns:
164     *    OK if no more buffers need to be preallocated
165     *    NOT_ENOUGH_DATA if calls to prepareNextBuffer are needed to finish
166     *        buffer pre-allocation, and transitions to the PREPARING state.
167     *    NO_INIT in case of a serious error from the HAL device
168     *    INVALID_OPERATION if called when not in CONFIGURED state, or a
169     *        valid buffer has already been returned to this stream.
170     */
171    virtual status_t startPrepare(int maxCount) = 0;
172
173    /**
174     * Check if the stream is mid-preparing.
175     */
176    virtual bool     isPreparing() const = 0;
177
178    /**
179     * Continue stream buffer preparation by allocating the next
180     * buffer for this stream.  May only be called in the PREPARED state.
181     *
182     * Returns OK and transitions to the CONFIGURED state if all buffers
183     * are allocated after the call concludes. Otherwise returns NOT_ENOUGH_DATA.
184     *
185     * Returns:
186     *    OK if no more buffers need to be preallocated, and transitions
187     *        to the CONFIGURED state.
188     *    NOT_ENOUGH_DATA if more calls to prepareNextBuffer are needed to finish
189     *        buffer pre-allocation.
190     *    NO_INIT in case of a serious error from the HAL device
191     *    INVALID_OPERATION if called when not in CONFIGURED state, or a
192     *        valid buffer has already been returned to this stream.
193     */
194    virtual status_t prepareNextBuffer() = 0;
195
196    /**
197     * Cancel stream preparation early. In case allocation needs to be
198     * stopped, this method transitions the stream back to the CONFIGURED state.
199     * Buffers that have been allocated with prepareNextBuffer remain that way,
200     * but a later use of prepareNextBuffer will require just as many
201     * calls as if the earlier prepare attempt had not existed.
202     *
203     * Returns:
204     *    OK if cancellation succeeded, and transitions to the CONFIGURED state
205     *    INVALID_OPERATION if not in the PREPARING state
206     *    NO_INIT in case of a serious error from the HAL device
207     */
208    virtual status_t cancelPrepare() = 0;
209
210    /**
211     * Tear down memory for this stream. This frees all unused gralloc buffers
212     * allocated for this stream, but leaves it ready for operation afterward.
213     *
214     * May only be called in the CONFIGURED state, and keeps the stream in
215     * the CONFIGURED state.
216     *
217     * Returns:
218     *    OK if teardown succeeded.
219     *    INVALID_OPERATION if not in the CONFIGURED state
220     *    NO_INIT in case of a serious error from the HAL device
221     */
222    virtual status_t tearDown() = 0;
223
224    /**
225     * Fill in the camera3_stream_buffer with the next valid buffer for this
226     * stream, to hand over to the HAL.
227     *
228     * Multiple surfaces could share the same HAL stream, but a request may
229     * be only for a subset of surfaces. In this case, the
230     * Camera3StreamInterface object needs the surface ID information to acquire
231     * buffers for those surfaces. For the case of single surface for a HAL
232     * stream, surface_ids parameter has no effect.
233     *
234     * This method may only be called once finishConfiguration has been called.
235     * For bidirectional streams, this method applies to the output-side
236     * buffers.
237     *
238     */
239    virtual status_t getBuffer(camera3_stream_buffer *buffer,
240            const std::vector<size_t>& surface_ids = std::vector<size_t>()) = 0;
241
242    /**
243     * Return a buffer to the stream after use by the HAL.
244     *
245     * This method may only be called for buffers provided by getBuffer().
246     * For bidirectional streams, this method applies to the output-side buffers
247     */
248    virtual status_t returnBuffer(const camera3_stream_buffer &buffer,
249            nsecs_t timestamp) = 0;
250
251    /**
252     * Fill in the camera3_stream_buffer with the next valid buffer for this
253     * stream, to hand over to the HAL.
254     *
255     * This method may only be called once finishConfiguration has been called.
256     * For bidirectional streams, this method applies to the input-side
257     * buffers.
258     *
259     * Normally this call will block until the handed out buffer count is less than the stream
260     * max buffer count; if respectHalLimit is set to false, this is ignored.
261     */
262    virtual status_t getInputBuffer(camera3_stream_buffer *buffer, bool respectHalLimit = true) = 0;
263
264    /**
265     * Return a buffer to the stream after use by the HAL.
266     *
267     * This method may only be called for buffers provided by getBuffer().
268     * For bidirectional streams, this method applies to the input-side buffers
269     */
270    virtual status_t returnInputBuffer(const camera3_stream_buffer &buffer) = 0;
271
272    /**
273     * Get the buffer producer of the input buffer queue.
274     *
275     * This method only applies to input streams.
276     */
277    virtual status_t getInputBufferProducer(sp<IGraphicBufferProducer> *producer) = 0;
278
279    /**
280     * Whether any of the stream's buffers are currently in use by the HAL,
281     * including buffers that have been returned but not yet had their
282     * release fence signaled.
283     */
284    virtual bool     hasOutstandingBuffers() const = 0;
285
286    enum {
287        TIMEOUT_NEVER = -1
288    };
289
290    /**
291     * Set the state tracker to use for signaling idle transitions.
292     */
293    virtual status_t setStatusTracker(sp<StatusTracker> statusTracker) = 0;
294
295    /**
296     * Disconnect stream from its non-HAL endpoint. After this,
297     * start/finishConfiguration must be called before the stream can be used
298     * again. This cannot be called if the stream has outstanding dequeued
299     * buffers.
300     */
301    virtual status_t disconnect() = 0;
302
303    /**
304     * Return if the buffer queue of the stream is abandoned.
305     */
306    virtual bool isAbandoned() const = 0;
307
308    /**
309     * Debug dump of the stream's state.
310     */
311    virtual void     dump(int fd, const Vector<String16> &args) const = 0;
312
313    virtual void     addBufferListener(
314            wp<Camera3StreamBufferListener> listener) = 0;
315    virtual void     removeBufferListener(
316            const sp<Camera3StreamBufferListener>& listener) = 0;
317
318    /**
319     * Setting listner will remove previous listener (if exists)
320     * Only allow set listener during stream configuration because stream is guaranteed to be IDLE
321     * at this state, so setBufferFreedListener won't collide with onBufferFreed callbacks.
322     * Client is responsible to keep the listener object alive throughout the lifecycle of this
323     * Camera3Stream.
324     */
325    virtual void setBufferFreedListener(wp<Camera3StreamBufferFreedListener> listener) = 0;
326};
327
328} // namespace camera3
329
330} // namespace android
331
332#endif
333