Argus API Argus Camera API

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- File List
- File Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Stream.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of NVIDIA CORPORATION nor the names of its
13 * contributors may be used to endorse or promote products derived
14 * from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
20 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
23 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
24 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 #ifndef _ARGUS_STREAM_H
30 #define _ARGUS_STREAM_H
31
32 namespace Argus
33 {
34
35 DEFINE_NAMED_UUID_CLASS(StreamMode);
36 DEFINE_UUID(StreamMode, STREAM_MODE_MAILBOX, 33661d40,3ee2,11e6,bdf4,08,00,20,0c,9a,66);
37 DEFINE_UUID(StreamMode, STREAM_MODE_FIFO, 33661d41,3ee2,11e6,bdf4,08,00,20,0c,9a,66);
38
39 /**
40 * Input streams are created and owned by CaptureSessions, and they maintain
41 * a connection with an EGLStream in order to acquire frames as an EGLStream consumer.
42 */
43 class InputStream : public InterfaceProvider, public Destructable
44 {
45 protected:
46 ~InputStream() {}
47 };
48
49 /**
50 * Output streams are created and owned by CaptureSessions, and they maintain
51 * a connection with an EGLStream in order to present frames as an EGLStream producer.
52 */
53 class OutputStream : public InterfaceProvider, public Destructable
54 {
55 protected:
56 ~OutputStream() {}
57 };
58
59 /**
60 * Settings for OutputStream creation are exposed by the OutputStreamSettings class.
61 * These are created by CaptureSessions and used for calls to ICaptureSession::createOutputStream.
62 */
63 class OutputStreamSettings : public InterfaceProvider, public Destructable
64 {
65 protected:
66 ~OutputStreamSettings() {}
67 };
68
69 /**
70 * @class IStream
71 *
72 * Interface that exposes the properties common to all Stream objects.
73 */
74 DEFINE_UUID(InterfaceID, IID_STREAM, 8f50dade,cc26,4ec6,9d2e,d9,d0,19,2a,ef,06);
75
76 class IStream : public Interface
77 {
78 public:
79 static const InterfaceID& id() { return IID_STREAM; }
80
81 /**
82 * Waits until both the producer and consumer endpoints of the stream are connected.
83 *
84 * @param[in] timeout The timeout in nanoseconds.
85 *
86 * @returns success/status of this call.
87 */
88 virtual Status waitUntilConnected(uint64_t timeout = TIMEOUT_INFINITE) const = 0;
89
90 /**
91 * Disconnects the stream from the underlying EGLStream.
92 */
93 virtual void disconnect() = 0;
94
95 /**
96 * Returns the format of the stream.
97 */
98 virtual PixelFormat getPixelFormat() const = 0;
99
100 /**
101 * Returns the image resolution of the stream, in pixels.
102 */
103 virtual Size getResolution() const = 0;
104
105 /**
106 * Returns the EGLDisplay the stream's EGLStream belongs to.
107 */
108 virtual EGLDisplay getEGLDisplay() const = 0;
109
110 /**
111 * Returns the EGLStream backing the stream.
112 */
113 virtual EGLStreamKHR getEGLStream() const = 0;
114
115 protected:
116 ~IStream() {}
117 };
118
119 /**
120 * @class IOutputStreamSettings
121 *
122 * Interface that exposes the settings used for OutputStream creation.
123 */
124 DEFINE_UUID(InterfaceID, IID_OUTPUT_STREAM_SETTINGS, 52f2b830,3d52,11e6,bdf4,08,00,20,0c,9a,66);
125
126 class IOutputStreamSettings : public Interface
127 {
128 public:
129 static const InterfaceID& id() { return IID_OUTPUT_STREAM_SETTINGS; }
130
131 /**
132 * Set the format of the stream.
133 * Default value: PIXEL_FMT_UNKNOWN
134 */
135 virtual Status setPixelFormat(const PixelFormat& format) = 0;
136 virtual PixelFormat getPixelFormat() const = 0;
137
138 /**
139 * Set the resolution of the stream.
140 * Default value: (0, 0)
141 */
142 virtual Status setResolution(const Size& resolution) = 0;
143 virtual Size getResolution() const = 0;
144
145 /**
146 * Set the camera device to use as the source for this stream.
147 * Default value: First available device in the session.
148 */
149 virtual Status setCameraDevice(CameraDevice* device) = 0;
150 virtual CameraDevice* getCameraDevice() const = 0;
151
152 /**
153 * Set the EGLDisplay the created stream must belong to.
154 * Default value: EGL_NO_DISPLAY - stream is display-agnostic.
155 */
156 virtual Status setEGLDisplay(EGLDisplay eglDisplay) = 0;
157 virtual EGLDisplay getEGLDisplay() const = 0;
158
159 /**
160 * Sets the mode of the OutputStream. Available options are:
161 *
162 * MAILBOX:
163 * In this mode, only the newest frame is made available to the consumer. When Argus
164 * completes a frame it empties the mailbox and inserts the new frame into the mailbox.
165 * The consumer then retrieves the frame from the mailbox and processes it; when
166 * finished, the frame is either placed back into the mailbox (if the mailbox is empty)
167 * or discarded (if the mailbox is not empty). This mode implies 2 things:
168 *
169 * - If the consumer consumes frames slower than Argus produces frames, then some
170 * frames may be lost (never seen by the consumer).
171 *
172 * - If the consumer consumes frames faster than Argus produces frames, then the
173 * consumer may see some frames more than once.
174 *
175 * FIFO:
176 * When using this mode, every producer frame is made available to the consumer through
177 * the use of a fifo queue for the frames. When using this mode, the fifo queue length
178 * must be specified using setFifoLength. When Argus completes a frame it inserts it to
179 * the head of the fifo queue. If the fifo is full (already contains the number of frames
180 * equal to the fifo queue length), Argus will stall until the fifo is no longer
181 * full. The consumer consumes frames from the tail of the queue; however, if the
182 * consumer releases a frame while the queue is empty, the frame is set aside and will
183 * be returned again the next time the consumer requests a frame if another new frame
184 * has not been inserted into the fifo queue before then. Once a new frame is inserted
185 * into the fifo queue, any previously released frame will be permanently discarded.
186 * This mode implies:
187 *
188 * - Frames are never discarded until the consumer has processed them.
189 *
190 * - If the consumer consumes frames slower than Argus produces them, Argus will stall.
191 *
192 * - If the consumer consumes frames faster than Argus produces them, then the
193 * consumer may see some frames more than once.
194 *
195 * Default value: STREAM_MODE_MAILBOX
196 */
197 virtual Status setMode(const StreamMode& mode) = 0;
198 virtual StreamMode getMode() const = 0;
199
200 /**
201 * Sets the FIFO queue length of the stream. This value is only used if the stream is using
202 * the FIFO mode (@see OutputStreamSettings::setMode). Value must be > 0.
203 * Default value: 1
204 */
205 virtual Status setFifoLength(uint32_t fifoLength) = 0;
206 virtual uint32_t getFifoLength() const = 0;
207
208 protected:
209 ~IOutputStreamSettings() {}
210 };
211
212 } // namespace Argus
213
214 #endif // _ARGUS_STREAM_H