Libargus API
Libargus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
BufferStream.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017-2018, 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: BufferStream API</b>
32  *
33  * @b Description: Defines an OutputStream type used to write to application-managed buffers.
34  */
35 
36 #ifndef _ARGUS_BUFFER_STREAM_H
37 #define _ARGUS_BUFFER_STREAM_H
38 
39 namespace Argus
40 {
41 
42 /**
43  * @defgroup ArgusBufferOutputStream BufferOutputStream
44  * @ingroup ArgusOutputStream
45  * @ref ArgusOutputStream type that writes to application-managed buffers (STREAM_TYPE_BUFFER).
46  *
47  * Buffer-based OutputStream objects maintain a set of Buffer objects that are
48  * created by the application to wrap native image buffers allocated and owned
49  * by the application. These Buffer objects do not take possession of the native
50  * resources, which continue to be owned by the application; rather, they are used
51  * to control data access between libargus (as capture results are written) and the
52  * application (as the capture results are read).
53  *
54  * Every Buffer stream is associated with a single BufferType, which corresponds
55  * to the native resource type that is being wrapped by its Buffers. This BufferType
56  * dictates which interfaces will be supported by the OutputStream and the child
57  * BufferSettings and Buffer objects created by it, and is immutable after stream
58  * creation.
59  *
60  * In addition to image data, Buffer objects may be optionally used to transport
61  * sync information between libargus and the application in order to support hardware
62  * level synchronization and pipelining across the API boundary. The type of sync
63  * information, and the sync interfaces supported by a Buffer, is controlled by
64  * the SyncType.
65  */
66 /**
67  * @defgroup ArgusBufferOutputStreamSettings BufferOutputStreamSettings
68  * @ingroup ArgusOutputStreamSettings
69  * Settings type used to configure/create @ref ArgusBufferOutputStream streams (STREAM_TYPE_BUFFER).
70  */
71 
72 /**
73  * @ref ArgusOutputStream type that writes to application-managed Buffers.
74  * @ingroup ArgusOutputStreamSettings
75  */
76 DEFINE_UUID(StreamType, STREAM_TYPE_BUFFER, c723d960,5231,11e7,9598,18,00,20,0c,9a,66);
77 
78 /**
79  * @defgroup ArgusBufferBuffer Buffer Types
80  * @ingroup ArgusBuffer
81  * The buffer type describes the type of the image resource being wrapped by the @ref ArgusBuffer.
82  */
83 /**
84  * @defgroup ArgusBufferBufferSettings Buffer Types
85  * @ingroup ArgusBufferSettings
86  * Provides buffer type specific configuration settings.
87  */
88 DEFINE_NAMED_UUID_CLASS(BufferType);
89 DEFINE_UUID(BufferType, BUFFER_TYPE_NONE, c723d961,5231,11e7,9598,18,00,20,0c,9a,66);
90 
91 /**
92  * @defgroup ArgusBufferSync Sync Types
93  * @ingroup ArgusBuffer
94  * The sync type describes the type of sync object to use with the @ref ArgusBuffer.
95  */
96 /**
97  * @defgroup ArgusBufferBufferSettings Buffer Types
98  * @ingroup ArgusBufferSettings
99  * Provides sync type specific configuration settings.
100  */
101 DEFINE_NAMED_UUID_CLASS(SyncType);
102 DEFINE_UUID(SyncType, SYNC_TYPE_NONE, c723d962,5231,11e7,9598,18,00,20,0c,9a,66);
103 
104 /**
105  * Object that wraps an application-managed buffer for use as a capture request destination.
106  *
107  * Every Buffer is associated with a single BufferType, which corresponds to the
108  * native resource type that is being wrapped by it, and dictates which interfaces
109  * it will support.
110  *
111  * In addition to image data, Buffer objects may optionally transport sync
112  * information between libargus and the application in order to support hardware
113  * level synchronization and pipelining across the API boundary. The type of sync
114  * information, and the sync interfaces supported by a Buffer, is controlled by
115  * the SyncType.
116  *
117  * All Buffer objects will support the IBuffer interface in order to query the
118  * core BufferType and SyncType.
119  *
120  * @defgroup ArgusBuffer Buffer
121  * @ingroup ArgusObjects
122  */
123 class Buffer : public InterfaceProvider, public Destructable
124 {
125 protected:
126  ~Buffer() {}
127 };
128 
129 /**
130  * Container for settings used to configure/create a @ref ArgusBuffer.
131  *
132  * These objects are created by IBufferOutputStream::createBufferSettings, and
133  * are used to configure the various parameters required for Buffer creation.
134  * Since the Buffer OutputStream which creates this object uses a single
135  * BufferType and SyncType, the interfaces supported by BufferSettings objects
136  * are dictated by these types.
137  *
138  * @defgroup ArgusBufferSettings BufferSettings
139  * @ingroup ArgusObjects
140  */
142 {
143 protected:
145 };
146 
147 /**
148  * @class IBufferOutputStreamSettings
149  *
150  * Interface that exposes the configuration available to Buffer-based OutputStreams.
151  *
152  * @ingroup ArgusBufferOutputStreamSettings
153  */
154 DEFINE_UUID(InterfaceID, IID_BUFFER_OUTPUT_STREAM_SETTINGS,
155  c723d963,5231,11e7,9598,18,00,20,0c,9a,66);
157 {
158 public:
159  static const InterfaceID& id() { return IID_BUFFER_OUTPUT_STREAM_SETTINGS; }
160 
161  /**
162  * Sets the BufferType for the stream. This controls which type of native buffer
163  * type will be wrapped by this OutputStream, and thus will dictate which interfaces
164  * are supported by the OutputStream and child BufferSettings and Buffer objects.
165  * This value defaults to BUFFER_TYPE_NONE and must be set by the application
166  * to a BufferType supported by this libargus implementation.
167  *
168  * @param[in] type The BufferType to use for the new OutputStream.
169  */
170  virtual Status setBufferType(const BufferType& type) = 0;
171 
172  /**
173  * Returns the BufferType to be used for the stream.
174  */
175  virtual BufferType getBufferType() const = 0;
176 
177  /**
178  * Sets the SyncType for the stream. This controls which type of native sync
179  * information will be attached to Buffers for sync support between libargus
180  * and the application.
181  * This value defaults to SYNC_TYPE_NONE, which means that no sync information
182  * will be supported. In this case, both the application and libargus are
183  * expected to be done all read and/or write operations before passing the
184  * Buffer to the other.
185  *
186  * @param[in] type The SyncType to use for the new OutputStream.
187  */
188  virtual Status setSyncType(const SyncType& type) = 0;
189 
190  /**
191  * Returns the SyncType to be used for the stream.
192  */
193  virtual SyncType getSyncType() const = 0;
194 
195  /**
196  * Sets the metadata enable for the stream. When metadata is enabled, a CaptureMetadata
197  * object may be attached to each Buffer when it is output from libargus as the result
198  * of a successful capture request (see IBuffer::getMetadata).
199  *
200  * @param[in] enable Whether or not metadata is enabled for the stream.
201  */
202  virtual void setMetadataEnable(bool enable) = 0;
203 
204  /**
205  * Returns the metadata enable.
206  */
207  virtual bool getMetadataEnable() const = 0;
208 
209 protected:
211 };
212 
213 /**
214  * @class IBufferOutputStream
215  *
216  * Interface that provides the methods used with Buffer-based OutputStreams.
217  *
218  * @ingroup ArgusBufferOutputStream
219  */
220 DEFINE_UUID(InterfaceID, IID_BUFFER_OUTPUT_STREAM, c723d964,5231,11e7,9598,18,00,20,0c,9a,66);
222 {
223 public:
224  static const InterfaceID& id() { return IID_BUFFER_OUTPUT_STREAM; }
225 
226  /**
227  * Returns the BufferType of the stream.
228  */
229  virtual BufferType getBufferType() const = 0;
230 
231  /**
232  * @returns the SyncType of the stream.
233  */
234  virtual SyncType getSyncType() const = 0;
235 
236  /**
237  * Creates a BufferSettings object. This Destructable object is used to configure
238  * the settings for a new Buffer object, including things like the native buffer
239  * handle that is to be wrapped by the Buffer. The interfaces and settings that
240  * are supported by the new BufferSettings object are dictated by the BufferType
241  * and SyncType of the creating OutputStream.
242  *
243  * @param[out] status An optional pointer to return success/status.
244  *
245  * @returns a new BufferSettings, or NULL on failure (error code written to 'status').
246  */
247  virtual BufferSettings* createBufferSettings(Status* status = NULL) = 0;
248 
249  /**
250  * Creates a Buffer object. All of the settings used to configure Buffer creation
251  * are provided by the BufferSettings object (which continues to be owned by the
252  * application and can be reused until destroyed).
253  *
254  * New Buffer objects are returned to the application in the "acquired" state,
255  * meaning that the application must call releaseBuffer on the Buffer before it
256  * may be used by libargus.
257  *
258  * @param[in] settings the buffer settings to use for Buffer creation.
259  * @param[out] status An optional pointer to return success/status.
260  *
261  * @returns a new BufferSettings, or NULL on failure (error code written to 'status').
262  */
263  virtual Buffer* createBuffer(const BufferSettings* settings, Status* status = NULL) = 0;
264 
265  /**
266  * Acquires a Buffer from the stream that was written to by a libargus capture request.
267  *
268  * Buffers are acquired from the stream in FIFO order relative to when they are
269  * produced by libargus (which may not match the original request submission order).
270  * If a non-zero timeout is provided, this operation will block until a new Buffer
271  * is produced by libargus or the timeout period is exceeded.
272  *
273  * Once a Buffer has been acquired, the application will have exclusive access to the
274  * Buffer's image data, which it will retain until the Buffer is released back to the
275  * stream for further capture request use via releaseBuffer. Buffers may also be
276  * destroyed while acquired; doing so prevents any further use of the Buffer object
277  * within the Stream and releases any buffer resources or references held by the Buffer
278  * object.
279  *
280  * If sync support has been enabled for this Stream/Buffer (ie. SyncType is not
281  * STREAM_TYPE_NONE), hardware synchronization capabilities may be used to allow hardware
282  * operations on a Buffer to still be pending when it is acquired from or released back to
283  * libargus. In this case, the returned Buffer will contain the output sync information
284  * provided by libargus which the application must obey before accessing the Buffer's
285  * image data. Similarly, the application may need to write input sync information to
286  * the Buffer before calling releaseBuffer such that libargus will obey the sync before
287  * the Buffer is written to by a new capture request. The exact mechanism used for reading
288  * and writing this sync state depends on and is documented by the various SyncTypes and
289  * their corresponding interfaces.
290  *
291  * @param[in] timeout The amount of time to allow for the acquire.
292  * @param[out] status An optional pointer to return success/status.
293  *
294  * @returns A Buffer that has been written to by a capture request
295  */
296  virtual Buffer* acquireBuffer(uint64_t timeout = TIMEOUT_INFINITE, Status* status = NULL) = 0;
297 
298  /**
299  * Release a Buffer back to the stream to make it available for a future capture request.
300  *
301  * Once a Buffer has been released to the Stream, libargus will have exclusive access to
302  * the Buffer's image resources until it is once again acquired by the application via
303  * acquireBuffer. Any buffer access outside of libargus during this time may lead to
304  * undefined results.
305  *
306  * While it is often the case that Buffers may be used by libargus in the order they are
307  * released, this is not a requirement; libargus may reuse Buffers in any order once they
308  * have been released.
309  *
310  * If sync support has been enabled for this StreamBuffer (ie. SyncType is not
311  * STREAM_TYPE_NONE), sync information may need to be written to the Buffer by the client
312  * before releaseBuffer is called. The exact mechanism used for writing this sync state
313  * depends on and is documented by the various SyncTypes and their corresponding interfaces.
314  *
315  * Note that while it is safe to destroy a Buffer object while it has been released to
316  * libargus, it is possible that pending requests may be using this Buffer and may still
317  * output Events that reference the Buffer object, and so the application is responsible
318  * for making sure that it does not use any Buffer object that it has previously destroyed.
319  * If there are no pending requests using a particular Stream, destroying any of its
320  * released Buffers will prevent them from ever being used or returned by libargus again.
321  *
322  * @param[in] buffer The Buffer to release back to the stream.
323  */
324  virtual Status releaseBuffer(Buffer* buffer) = 0;
325 
326  /**
327  * Signals the end of the stream.
328  *
329  * Once the end of stream has been signalled on a stream, any call made to acquireBuffer
330  * will immediately (ignoring the timeout parameter) return NULL with a STATUS_END_OF_STREAM
331  * status when the following is true:
332  * 1) There are no Buffers immediately available to be acquired, and
333  * 2) There are no capture requests pending writes to the stream.
334  * This implies that no pending or completed frames will be lost, and that all pending or
335  * completed frames must be acquired before an END_OF_STREAM status is returned.
336  *
337  * If any thread is blocked in acquireBuffer when the end of stream is signalled, and the
338  * above conditions are met, then that thread will unblock and return END_OF_STREAM immediately.
339  */
340  virtual Status endOfStream() = 0;
341 
342 protected:
344 };
345 
346 /**
347  * @class IBuffer
348  *
349  * Interface that provides the core methods for Buffer objects.
350  *
351  * @ingroup ArgusBuffer
352  */
353 DEFINE_UUID(InterfaceID, IID_BUFFER, c723d965,5231,11e7,9598,18,00,20,0c,9a,66);
354 class IBuffer : public Interface
355 {
356 public:
357  static const InterfaceID& id() { return IID_BUFFER; }
358 
359  /**
360  * Returns the BufferType of the Buffer.
361  */
362  virtual BufferType getBufferType() const = 0;
363 
364  /**
365  * Returns the SyncType of the Buffer.
366  */
367  virtual SyncType getSyncType() const = 0;
368 
369  /**
370  * Sets the client data for the Buffer.
371  * This is provided as a convenience for applications to be able to map Buffers to
372  * other client-managed data. It is not used at all by the libargus implementation,
373  * and is returned as-is by getClientData.
374  * Default value: NULL
375  *
376  * @param[in] clientData The client data pointer to set in the buffer.
377  */
378  virtual void setClientData(const void* clientData) = 0;
379 
380  /**
381  * Returns the client data from the Buffer.
382  */
383  virtual const void* getClientData() const = 0;
384 
385  /**
386  * Returns the CaptureMetadata object that was attached to this Buffer when it was last
387  * output to the stream from the result of a successful capture request.
388  *
389  * This method should only ever be called while the Buffer is in an acquired state; ie. the
390  * time between when the Buffer was acquired by IBufferOutputStream::acquireBuffer and when
391  * it was released by IBufferOutputStream::releaseBuffer. If called outside of the acquired
392  * state, NULL will be returned. Similarly, the returned object will only remain valid so
393  * long as the Buffer is acquired -- if this object or any of its interfaces are accessed
394  * outside of the acquired state, undefined results or abnormal process termination may occur.
395  *
396  * Metadata will only be written if metadata is enabled for the stream (see
397  * IBufferOutputStreamSettings::setMetadataEnable). NULL may also still be returned if there
398  * were any capture errors or metadata is otherwise unavailable.
399  */
400  virtual const CaptureMetadata* getMetadata() const = 0;
401 
402 protected:
403  ~IBuffer() {}
404 };
405 
406 } // namespace Argus
407 
408 #endif // _ARGUS_BUFFER_STREAM_H