Libargus API Libargus Camera API

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

- File List
- File Members

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 ArgusOutputStream 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 */
141 class BufferSettings : public InterfaceProvider, public Destructable
142 {
143 protected:
144 ~BufferSettings() {}
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);
156 class IBufferOutputStreamSettings : public Interface
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:
210 ~IBufferOutputStreamSettings() {}
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);
221 class IBufferOutputStream : public Interface
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:
343 ~IBufferOutputStream() {}
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