Libargus API
Libargus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
EGLStream.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017-2022, 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 /**
30  * @file
31  * <b>Libargus API: EGLStream API</b>
32  *
33  * @b Description: This file defines an EGLStream-linked Output/Input Stream type.
34  */
35 
36 #ifndef _ARGUS_EGL_STREAM_H
37 #define _ARGUS_EGL_STREAM_H
38 
39 namespace Argus
40 {
41 
42 /**
43  * @defgroup ArgusEGLOutputStream EGLOutputStream
44  * @ingroup ArgusOutputStream
45  * @ref ArgusOutputStream type that generates frames as an EGLStream producer (STREAM_TYPE_EGL).
46  *
47  * EGLStream-linked OutputStream objects maintain a connection to an EGLStream
48  * as the producer endpoint. The EGLStream implementation is responsible for
49  * buffer allocation, management, and synchronization as frames are presented
50  * to the EGLStream from libargus and then consumed using an EGLStream consumer.
51  */
52 /**
53  * @defgroup ArgusEGLOutputStreamSettings EGLOutputStreamSettings
54  * @ingroup ArgusOutputStreamSettings
55  * Settings type used to configure/create @ref ArgusEGLOutputStream streams (STREAM_TYPE_EGL).
56  */
57 
58 /**
59  * @defgroup ArgusEGLInputStream EGLInputStream
60  * @ingroup ArgusInputStream
61  * @ref ArgusInputStream type that generates frames as an EGLStream consumer (STREAM_TYPE_EGL).
62  *
63  * EGLStream-linked InputStream objects maintain a connection to an EGLStream
64  * as the consumer startingpoint. The EGLStream implementation is responsible for
65  * buffer allocation, management, and synchronization as frames are produced by EGLStream
66  * consumer and presented to EGLStream to be further consumed by InputStream consumer
67  * in libargus.
68  */
69 /**
70  * @defgroup ArgusEGLInputStreamSettings EGLInputStreamSettings
71  * @ingroup ArgusInputStreamSettings
72  * Settings type used to configure/create @ref ArgusEGLInputStream streams (STREAM_TYPE_EGL).
73  */
74 
75 /**
76  * @ref ArgusOutputStream type that generates frames as an EGLStream producer (STREAM_TYPE_EGL).
77  * @ingroup ArgusOutputStreamSettings
78  */
79 /**
80  * @ref ArgusInputStream type that generates frames as an EGLStream producer (STREAM_TYPE_EGL).
81  * @ingroup ArgusInputStream ArgusInputStreamSettings
82  */
83 DEFINE_UUID(StreamType, STREAM_TYPE_EGL, 3a659360,5231,11e7,9598,18,00,20,0c,9a,66);
84 
85 /**
86  * Defines the EGLStream queue mode of operation (see IEGLOutputStreamSettings::setMode).
87  */
88 DEFINE_NAMED_UUID_CLASS(EGLStreamMode);
89 DEFINE_UUID(EGLStreamMode, EGL_STREAM_MODE_MAILBOX, 33661d40,3ee2,11e6,bdf4,08,00,20,0c,9a,66);
90 DEFINE_UUID(EGLStreamMode, EGL_STREAM_MODE_FIFO, 33661d41,3ee2,11e6,bdf4,08,00,20,0c,9a,66);
91 
92 /**
93  * @class IEGLOutputStreamSettings
94  *
95  * Interface that exposes the settings used for EGLStream-linked OutputStream creation.
96  *
97  * @ingroup ArgusEGLOutputStreamSettings
98  */
99 DEFINE_UUID(InterfaceID, IID_EGL_OUTPUT_STREAM_SETTINGS, 3a659361,5231,11e7,9598,18,00,20,0c,9a,66);
101 {
102 public:
103  static const InterfaceID& id() { return IID_EGL_OUTPUT_STREAM_SETTINGS; }
104 
105  /**
106  * Set the format of the stream.
107  * Default value: PIXEL_FMT_UNKNOWN
108  */
109  virtual Status setPixelFormat(const PixelFormat& format) = 0;
110  virtual PixelFormat getPixelFormat() const = 0;
111 
112  /**
113  * Set the resolution of the stream.
114  * Default value: (0, 0)
115  */
116  virtual Status setResolution(const Size2D<uint32_t>& resolution) = 0;
117  virtual Size2D<uint32_t> getResolution() const = 0;
118 
119  /**
120  * Set the number of exposures per stream frame.
121  * This number should match the number of exposures that are going to be provided
122  * with each stream frame when capturing from multi-exposure WDR sources.
123  * Note that the EGLStream consumer must support consuming multi-exposure/buffer
124  * EGLStreams. In the case of the EGLStream::FrameConsumer consumer, the multiple
125  * exposures are treated as separate buffers in the acquired Image and may be
126  * accessed using any Image interface which supports multi-buffer/plane image access
127  * (see EGLStream::IImage::getBufferCount()).
128  * Default value: 1
129  */
130  virtual Status setExposureCount(uint32_t exposureCount) = 0;
131  virtual uint32_t getExposureCount() const = 0;
132 
133  /**
134  * Set the EGLDisplay the created stream must belong to.
135  * Default value: EGL_NO_DISPLAY - stream is display-agnostic.
136  */
137  virtual Status setEGLDisplay(EGLDisplay eglDisplay) = 0;
138  virtual EGLDisplay getEGLDisplay() const = 0;
139 
140  /**
141  * Sets the mode of the OutputStream. Available options are:
142  *
143  * MAILBOX:
144  * In this mode, only the newest frame is made available to the consumer. When Argus
145  * completes a frame it empties the mailbox and inserts the new frame into the mailbox.
146  * The consumer then retrieves the frame from the mailbox and processes it; when
147  * finished, the frame is either placed back into the mailbox (if the mailbox is empty)
148  * or discarded (if the mailbox is not empty). This mode implies 2 things:
149  *
150  * - If the consumer consumes frames slower than Argus produces frames, then some
151  * frames may be lost (never seen by the consumer).
152  *
153  * - If the consumer consumes frames faster than Argus produces frames, then the
154  * consumer may see some frames more than once.
155  *
156  * FIFO:
157  * When using this mode, every producer frame is made available to the consumer through
158  * the use of a fifo queue for the frames. When using this mode, the fifo queue length
159  * must be specified using setFifoLength. When Argus completes a frame it inserts it to
160  * the head of the fifo queue. If the fifo is full (already contains the number of frames
161  * equal to the fifo queue length), Argus will stall until the fifo is no longer
162  * full. The consumer consumes frames from the tail of the queue; however, if the
163  * consumer releases a frame while the queue is empty, the frame is set aside and will
164  * be returned again the next time the consumer requests a frame if another new frame
165  * has not been inserted into the fifo queue before then. Once a new frame is inserted
166  * into the fifo queue, any previously released frame will be permanently discarded.
167  * This mode implies:
168  *
169  * - Frames are never discarded until the consumer has processed them.
170  *
171  * - If the consumer consumes frames slower than Argus produces them, Argus will stall.
172  *
173  * - If the consumer consumes frames faster than Argus produces them, then the
174  * consumer may see some frames more than once.
175  *
176  * Default value: STREAM_MODE_MAILBOX
177  */
178  virtual Status setMode(const EGLStreamMode& mode) = 0;
179  virtual EGLStreamMode getMode() const = 0;
180 
181  /**
182  * Sets the FIFO queue length of the stream. This value is only used if the stream is using
183  * the FIFO mode (@see OutputStreamSettings::setMode). Value must be > 0.
184  * Default value: 1
185  */
186  virtual Status setFifoLength(uint32_t fifoLength) = 0;
187  virtual uint32_t getFifoLength() const = 0;
188 
189  /**
190  * Enables or disables embedding Argus CaptureMetadata within frames written to the EGLStream.
191  * Enabling this will allow an EGLStream::MetadataContainer to be created from frames acquired
192  * on the consumer side of the EGLStream that will expose the EGLStream::IArgusCaptureMetadata
193  * interface, which in turn provides access to the CaptureMetadata corresponding to that frame.
194  * This will also enable the IArgusCaptureMetadata interface directly on EGLStream::Frames
195  * acquired by an EGLStream::FrameConsumer.
196  * Default value: disabled.
197  */
198  virtual Status setMetadataEnable(bool metadataEnable) = 0;
199  virtual bool getMetadataEnable() const = 0;
200 
201  /**
202  * @returns True if the output pixel format is supported by the CaptureSession for the
203  * queried sensor mode. Otherwise, returns false.
204  *
205  * @param[in] sensorMode The sensor mode being queried for the output pixel type.
206  * @param[in] outputFormat The output pixel format being queried for support.
207  */
208  virtual bool supportsOutputStreamFormat(const SensorMode* sensorMode,
209  const PixelFormat& outputFormat) const = 0;
210 
211 protected:
213 };
214 
215 /**
216  * @class IEGLOutputStream
217  *
218  * Interface that exposes the methods available to an EGLStream-linked OutputStream.
219  *
220  * @ingroup ArgusEGLOutputStream
221  */
222 DEFINE_UUID(InterfaceID, IID_EGL_OUTPUT_STREAM, 3a659362,5231,11e7,9598,18,00,20,0c,9a,66);
224 {
225 public:
226  static const InterfaceID& id() { return IID_EGL_OUTPUT_STREAM; }
227 
228  /**
229  * Waits until both the producer and consumer endpoints of the stream are connected.
230  *
231  * @param[in] timeout The timeout in nanoseconds.
232  *
233  * @returns success/status of this call.
234  */
235  virtual Status waitUntilConnected(uint64_t timeout = TIMEOUT_INFINITE) const = 0;
236 
237  /**
238  * Disconnects the stream from the underlying EGLStream.
239  */
240  virtual void disconnect() = 0;
241 
242  /**
243  * Returns the format of the stream.
244  */
245  virtual PixelFormat getPixelFormat() const = 0;
246 
247  /**
248  * Returns the image resolution of the stream, in pixels.
249  */
250  virtual Size2D<uint32_t> getResolution() const = 0;
251 
252  /**
253  * Returns the EGLDisplay the stream's EGLStream belongs to.
254  */
255  virtual EGLDisplay getEGLDisplay() const = 0;
256 
257  /**
258  * Returns the EGLStream backing the stream.
259  */
260  virtual EGLStreamKHR getEGLStream() const = 0;
261 
262 protected:
264 };
265 
266 /**
267  * @class IEGLInputStreamSettings
268  *
269  * Interface that exposes the settings used for EGLStream-linked InputStream creation.
270  *
271  * @ingroup ArgusEGLInputStreamSettings
272  */
273 DEFINE_UUID(InterfaceID, IID_EGL_INPUT_STREAM_SETTINGS, c3579170,b1ac,11ec,a893,08,00,20,0c,9a,66);
275 {
276 public:
277  static const InterfaceID& id() { return IID_EGL_INPUT_STREAM_SETTINGS; }
278 
279  /**
280  * Set the format of the stream.
281  * Default value: PIXEL_FMT_UNKNOWN
282  */
283  virtual Status setPixelFormat(const PixelFormat& format) = 0;
284  virtual PixelFormat getPixelFormat() const = 0;
285 
286  /**
287  * Set the resolution of the stream.
288  * Default value: (0, 0)
289  */
290  virtual Status setResolution(const Size2D<uint32_t>& resolution) = 0;
291  virtual Size2D<uint32_t> getResolution() const = 0;
292 
293  /**
294  * Set the number of exposures per stream frame.
295  * This number should match the number of exposures that are going to be provided
296  * with each stream frame when capturing from multi-exposure WDR sources.
297  * Note that the EGLStream consumer must support consuming multi-exposure/buffer
298  * EGLStreams. In the case of the EGLStream::FrameConsumer consumer, the multiple
299  * exposures are treated as separate buffers in the acquired Image and may be
300  * accessed using any Image interface which supports multi-buffer/plane image access
301  * (see EGLStream::IImage::getBufferCount()).
302  * Default value: 1
303  */
304  virtual Status setExposureCount(uint32_t exposureCount) = 0;
305  virtual uint32_t getExposureCount() const = 0;
306 
307 
308  /**
309  * Set the EGLDisplay the created stream must belong to.
310  * Default value: EGL_NO_DISPLAY - stream is display-agnostic.
311  */
312  virtual Status setEGLDisplay(EGLDisplay eglDisplay) = 0;
313  virtual EGLDisplay getEGLDisplay() const = 0;
314 
315  /**
316  * Sets the FIFO queue length of the stream. This value must be > 0 as currently input streams
317  * only support FIFO mode of operation. In this mode every producer frame is made available to
318  * the consumer through the use of a fifo queue for the frames. If the fifo is full (already
319  * contains the number of frames equal to the fifo queue length), producer will stall until
320  * the fifo is no longer full. The consumer consumes frames from the tail of the queue,
321  * however, if the consumer releases a frame while the queue is empty, the frame is set aside
322  * and will be returned again the next time the consumer requests a frame if another new frame
323  * has not been inserted into the fifo queue before then. Once a new frame is inserted
324  * into the fifo queue, any previously released frame will be permanently discarded.
325  * This mode implies:
326  * - Frames are never discarded until the consumer has processed them.
327  *
328  * - If the consumer consumes frames slower than producer produces them, producer will stall.
329  *
330  * - If the consumer consumes frames faster than producer produces them, then the
331  * consumer may see some frames more than once.
332  *
333  * Default value: 1
334  */
335  virtual Status setFifoLength(uint32_t fifoLength) = 0;
336  virtual uint32_t getFifoLength() const = 0;
337 
338  /**
339  * @returns True if the input pixel format is supported by the CaptureSession for the
340  * queried sensor mode. Otherwise, returns false.
341  *
342  * @param[in] sensorMode The sensor mode being queried for the input pixel type.
343  * @param[in] inputFormat The input pixel format being queried for support.
344  */
345  virtual bool supportsInputStreamFormat(const SensorMode* sensorMode,
346  const PixelFormat& inputFormat) const = 0;
347 
348 protected:
350 };
351 
352 /**
353  * @class IEGLInputStream
354  *
355  * Interface that exposes the methods available to an EGLStream-linked InputStream.
356  *
357  * @ingroup ArgusEGLInputStream
358  */
359 DEFINE_UUID(InterfaceID, IID_EGL_INPUT_STREAM, c3579171,b1ac,11ec,a893,08,00,20,0c,9a,66)
361 {
362 public:
363  static const InterfaceID& id() { return IID_EGL_INPUT_STREAM; }
364 
365  /**
366  * Waits until both the consumer endpoints and producer of the stream are connected.
367  *
368  * @param[in] timeout The timeout in nanoseconds.
369  *
370  * @returns success/status of this call.
371  */
372  virtual Status waitUntilConnected(uint64_t timeout = TIMEOUT_INFINITE) const = 0;
373 
374  /**
375  * Disconnects the stream from the underlying EGLStream.
376  */
377  virtual void disconnect() = 0;
378 
379  /**
380  * Returns the format of the stream.
381  */
382  virtual PixelFormat getPixelFormat() const = 0;
383 
384  /**
385  * Returns the image resolution of the stream, in pixels.
386  */
387  virtual Size2D<uint32_t> getResolution() const = 0;
388 
389  /**
390  * Returns the EGLDisplay the stream's EGLStream belongs to.
391  */
392  virtual EGLDisplay getEGLDisplay() const = 0;
393 
394  /**
395  * Returns the EGLStream backing the stream.
396  */
397  virtual EGLStreamKHR getEGLStream() const = 0;
398 
399 protected:
401 };
402 
403 } // namespace Argus
404 
405 #endif // _ARGUS_EGL_STREAM_H