Argus API
Argus Camera API
 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  */
44 {
45 protected:
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  */
54 {
55 protected:
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  */
64 {
65 protected:
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 
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:
210 };
211 
212 } // namespace Argus
213 
214 #endif // _ARGUS_STREAM_H