Camera3StreamInterface.h revision 7b82efe7a376c882f8f938e1c41b8311a8cdda4a 
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
29/**
30 * An interface for managing a single stream of input and/or output data from
31 * the camera device.
32 */
33class Camera3StreamInterface : public virtual RefBase {
34  public:
35    /**
36     * Get the stream's ID
37     */
38    virtual int      getId() const = 0;
39
40    /**
41     * Get the stream's dimensions and format
42     */
43    virtual uint32_t getWidth() const = 0;
44    virtual uint32_t getHeight() const = 0;
45    virtual int      getFormat() const = 0;
46
47    /**
48     * Start the stream configuration process. Returns a handle to the stream's
49     * information to be passed into the HAL device's configure_streams call.
50     *
51     * Until finishConfiguration() is called, no other methods on the stream may
52     * be called. The usage and max_buffers fields of camera3_stream may be
53     * modified between start/finishConfiguration, but may not be changed after
54     * that. The priv field of camera3_stream may be modified at any time after
55     * startConfiguration.
56     *
57     * Returns NULL in case of error starting configuration.
58     */
59    virtual camera3_stream* startConfiguration() = 0;
60
61    /**
62     * Check if the stream is mid-configuration (start has been called, but not
63     * finish).  Used for lazy completion of configuration.
64     */
65    virtual bool    isConfiguring() const = 0;
66
67    /**
68     * Completes the stream configuration process. During this call, the stream
69     * may call the device's register_stream_buffers() method. The stream
70     * information structure returned by startConfiguration() may no longer be
71     * modified after this call, but can still be read until the destruction of
72     * the stream.
73     *
74     * Returns:
75     *   OK on a successful configuration
76     *   NO_INIT in case of a serious error from the HAL device
77     *   NO_MEMORY in case of an error registering buffers
78     *   INVALID_OPERATION in case connecting to the consumer failed
79     */
80    virtual status_t finishConfiguration(camera3_device *hal3Device) = 0;
81
82    /**
83     * Fill in the camera3_stream_buffer with the next valid buffer for this
84     * stream, to hand over to the HAL.
85     *
86     * This method may only be called once finishConfiguration has been called.
87     * For bidirectional streams, this method applies to the output-side
88     * buffers.
89     *
90     */
91    virtual status_t getBuffer(camera3_stream_buffer *buffer) = 0;
92
93    /**
94     * Return a buffer to the stream after use by the HAL.
95     *
96     * This method may only be called for buffers provided by getBuffer().
97     * For bidirectional streams, this method applies to the output-side buffers
98     */
99    virtual status_t returnBuffer(const camera3_stream_buffer &buffer,
100            nsecs_t timestamp) = 0;
101
102    /**
103     * Fill in the camera3_stream_buffer with the next valid buffer for this
104     * stream, to hand over to the HAL.
105     *
106     * This method may only be called once finishConfiguration has been called.
107     * For bidirectional streams, this method applies to the input-side
108     * buffers.
109     *
110     */
111    virtual status_t getInputBuffer(camera3_stream_buffer *buffer) = 0;
112
113    /**
114     * Return a buffer to the stream after use by the HAL.
115     *
116     * This method may only be called for buffers provided by getBuffer().
117     * For bidirectional streams, this method applies to the input-side buffers
118     */
119    virtual status_t returnInputBuffer(const camera3_stream_buffer &buffer) = 0;
120
121    /**
122     * Whether any of the stream's buffers are currently in use by the HAL,
123     * including buffers that have been returned but not yet had their
124     * release fence signaled.
125     */
126    virtual bool     hasOutstandingBuffers() const = 0;
127
128    enum {
129        TIMEOUT_NEVER = -1
130    };
131    /**
132     * Wait until the HAL is done with all of this stream's buffers, including
133     * signalling all release fences. Returns TIMED_OUT if the timeout is
134     * exceeded, OK on success. Pass in TIMEOUT_NEVER for timeout to indicate
135     * an indefinite wait.
136     */
137    virtual status_t waitUntilIdle(nsecs_t timeout) = 0;
138
139    /**
140     * Disconnect stream from its non-HAL endpoint. After this,
141     * start/finishConfiguration must be called before the stream can be used
142     * again. This cannot be called if the stream has outstanding dequeued
143     * buffers.
144     */
145    virtual status_t disconnect() = 0;
146
147    /**
148     * Debug dump of the stream's state.
149     */
150    virtual void     dump(int fd, const Vector<String16> &args) const = 0;
151
152    virtual void     addBufferListener(
153            wp<Camera3StreamBufferListener> listener) = 0;
154    virtual void     removeBufferListener(
155            const sp<Camera3StreamBufferListener>& listener) = 0;
156};
157
158} // namespace camera3
159
160} // namespace android
161
162#endif
163