|
- /*
- * Copyright (c) 2017-2018, NVIDIA CORPORATION. All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- * * Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- * * Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- * * Neither the name of NVIDIA CORPORATION nor the names of its
- * contributors may be used to endorse or promote products derived
- * from this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
- * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
- * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
- /**
- * @file
- * <b>Libargus API: BufferStream API</b>
- *
- * @b Description: Defines an OutputStream type used to write to application-managed buffers.
- */
-
- #ifndef _ARGUS_BUFFER_STREAM_H
- #define _ARGUS_BUFFER_STREAM_H
-
- namespace Argus
- {
-
- /**
- * @defgroup ArgusBufferOutputStream BufferOutputStream
- * @ingroup ArgusOutputStream
- * @ref ArgusOutputStream type that writes to application-managed buffers (STREAM_TYPE_BUFFER).
- *
- * Buffer-based OutputStream objects maintain a set of Buffer objects that are
- * created by the application to wrap native image buffers allocated and owned
- * by the application. These Buffer objects do not take possession of the native
- * resources, which continue to be owned by the application; rather, they are used
- * to control data access between libargus (as capture results are written) and the
- * application (as the capture results are read).
- *
- * Every Buffer stream is associated with a single BufferType, which corresponds
- * to the native resource type that is being wrapped by its Buffers. This BufferType
- * dictates which interfaces will be supported by the OutputStream and the child
- * BufferSettings and Buffer objects created by it, and is immutable after stream
- * creation.
- *
- * In addition to image data, Buffer objects may be optionally used to transport
- * sync information between libargus and the application in order to support hardware
- * level synchronization and pipelining across the API boundary. The type of sync
- * information, and the sync interfaces supported by a Buffer, is controlled by
- * the SyncType.
- */
- /**
- * @defgroup ArgusBufferOutputStreamSettings BufferOutputStreamSettings
- * @ingroup ArgusOutputStreamSettings
- * Settings type used to configure/create @ref ArgusBufferOutputStream streams (STREAM_TYPE_BUFFER).
- */
-
- /**
- * @ref ArgusOutputStream type that writes to application-managed Buffers.
- * @ingroup ArgusOutputStream ArgusOutputStreamSettings
- */
- DEFINE_UUID(StreamType, STREAM_TYPE_BUFFER, c723d960,5231,11e7,9598,18,00,20,0c,9a,66);
-
- /**
- * @defgroup ArgusBufferBuffer Buffer Types
- * @ingroup ArgusBuffer
- * The buffer type describes the type of the image resource being wrapped by the @ref ArgusBuffer.
- */
- /**
- * @defgroup ArgusBufferBufferSettings Buffer Types
- * @ingroup ArgusBufferSettings
- * Provides buffer type specific configuration settings.
- */
- DEFINE_NAMED_UUID_CLASS(BufferType);
- DEFINE_UUID(BufferType, BUFFER_TYPE_NONE, c723d961,5231,11e7,9598,18,00,20,0c,9a,66);
-
- /**
- * @defgroup ArgusBufferSync Sync Types
- * @ingroup ArgusBuffer
- * The sync type describes the type of sync object to use with the @ref ArgusBuffer.
- */
- /**
- * @defgroup ArgusBufferBufferSettings Buffer Types
- * @ingroup ArgusBufferSettings
- * Provides sync type specific configuration settings.
- */
- DEFINE_NAMED_UUID_CLASS(SyncType);
- DEFINE_UUID(SyncType, SYNC_TYPE_NONE, c723d962,5231,11e7,9598,18,00,20,0c,9a,66);
-
- /**
- * Object that wraps an application-managed buffer for use as a capture request destination.
- *
- * Every Buffer is associated with a single BufferType, which corresponds to the
- * native resource type that is being wrapped by it, and dictates which interfaces
- * it will support.
- *
- * In addition to image data, Buffer objects may optionally transport sync
- * information between libargus and the application in order to support hardware
- * level synchronization and pipelining across the API boundary. The type of sync
- * information, and the sync interfaces supported by a Buffer, is controlled by
- * the SyncType.
- *
- * All Buffer objects will support the IBuffer interface in order to query the
- * core BufferType and SyncType.
- *
- * @defgroup ArgusBuffer Buffer
- * @ingroup ArgusObjects
- */
- class Buffer : public InterfaceProvider, public Destructable
- {
- protected:
- ~Buffer() {}
- };
-
- /**
- * Container for settings used to configure/create a @ref ArgusBuffer.
- *
- * These objects are created by IBufferOutputStream::createBufferSettings, and
- * are used to configure the various parameters required for Buffer creation.
- * Since the Buffer OutputStream which creates this object uses a single
- * BufferType and SyncType, the interfaces supported by BufferSettings objects
- * are dictated by these types.
- *
- * @defgroup ArgusBufferSettings BufferSettings
- * @ingroup ArgusObjects
- */
- class BufferSettings : public InterfaceProvider, public Destructable
- {
- protected:
- ~BufferSettings() {}
- };
-
- /**
- * @class IBufferOutputStreamSettings
- *
- * Interface that exposes the configuration available to Buffer-based OutputStreams.
- *
- * @ingroup ArgusBufferOutputStreamSettings
- */
- DEFINE_UUID(InterfaceID, IID_BUFFER_OUTPUT_STREAM_SETTINGS,
- c723d963,5231,11e7,9598,18,00,20,0c,9a,66);
- class IBufferOutputStreamSettings : public Interface
- {
- public:
- static const InterfaceID& id() { return IID_BUFFER_OUTPUT_STREAM_SETTINGS; }
-
- /**
- * Sets the BufferType for the stream. This controls which type of native buffer
- * type will be wrapped by this OutputStream, and thus will dictate which interfaces
- * are supported by the OutputStream and child BufferSettings and Buffer objects.
- * This value defaults to BUFFER_TYPE_NONE and must be set by the application
- * to a BufferType supported by this libargus implementation.
- *
- * @param[in] type The BufferType to use for the new OutputStream.
- */
- virtual Status setBufferType(const BufferType& type) = 0;
-
- /**
- * Returns the BufferType to be used for the stream.
- */
- virtual BufferType getBufferType() const = 0;
-
- /**
- * Sets the SyncType for the stream. This controls which type of native sync
- * information will be attached to Buffers for sync support between libargus
- * and the application.
- * This value defaults to SYNC_TYPE_NONE, which means that no sync information
- * will be supported. In this case, both the application and libargus are
- * expected to be done all read and/or write operations before passing the
- * Buffer to the other.
- *
- * @param[in] type The SyncType to use for the new OutputStream.
- */
- virtual Status setSyncType(const SyncType& type) = 0;
-
- /**
- * Returns the SyncType to be used for the stream.
- */
- virtual SyncType getSyncType() const = 0;
-
- /**
- * Sets the metadata enable for the stream. When metadata is enabled, a CaptureMetadata
- * object may be attached to each Buffer when it is output from libargus as the result
- * of a successful capture request (see IBuffer::getMetadata).
- *
- * @param[in] enable Whether or not metadata is enabled for the stream.
- */
- virtual void setMetadataEnable(bool enable) = 0;
-
- /**
- * Returns the metadata enable.
- */
- virtual bool getMetadataEnable() const = 0;
-
- protected:
- ~IBufferOutputStreamSettings() {}
- };
-
- /**
- * @class IBufferOutputStream
- *
- * Interface that provides the methods used with Buffer-based OutputStreams.
- *
- * @ingroup ArgusBufferOutputStream
- */
- DEFINE_UUID(InterfaceID, IID_BUFFER_OUTPUT_STREAM, c723d964,5231,11e7,9598,18,00,20,0c,9a,66);
- class IBufferOutputStream : public Interface
- {
- public:
- static const InterfaceID& id() { return IID_BUFFER_OUTPUT_STREAM; }
-
- /**
- * Returns the BufferType of the stream.
- */
- virtual BufferType getBufferType() const = 0;
-
- /**
- * @returns the SyncType of the stream.
- */
- virtual SyncType getSyncType() const = 0;
-
- /**
- * Creates a BufferSettings object. This Destructable object is used to configure
- * the settings for a new Buffer object, including things like the native buffer
- * handle that is to be wrapped by the Buffer. The interfaces and settings that
- * are supported by the new BufferSettings object are dictated by the BufferType
- * and SyncType of the creating OutputStream.
- *
- * @param[out] status An optional pointer to return success/status.
- *
- * @returns a new BufferSettings, or NULL on failure (error code written to 'status').
- */
- virtual BufferSettings* createBufferSettings(Status* status = NULL) = 0;
-
- /**
- * Creates a Buffer object. All of the settings used to configure Buffer creation
- * are provided by the BufferSettings object (which continues to be owned by the
- * application and can be reused until destroyed).
- *
- * New Buffer objects are returned to the application in the "acquired" state,
- * meaning that the application must call releaseBuffer on the Buffer before it
- * may be used by libargus.
- *
- * @param[in] settings the buffer settings to use for Buffer creation.
- * @param[out] status An optional pointer to return success/status.
- *
- * @returns a new BufferSettings, or NULL on failure (error code written to 'status').
- */
- virtual Buffer* createBuffer(const BufferSettings* settings, Status* status = NULL) = 0;
-
- /**
- * Acquires a Buffer from the stream that was written to by a libargus capture request.
- *
- * Buffers are acquired from the stream in FIFO order relative to when they are
- * produced by libargus (which may not match the original request submission order).
- * If a non-zero timeout is provided, this operation will block until a new Buffer
- * is produced by libargus or the timeout period is exceeded.
- *
- * Once a Buffer has been acquired, the application will have exclusive access to the
- * Buffer's image data, which it will retain until the Buffer is released back to the
- * stream for further capture request use via releaseBuffer. Buffers may also be
- * destroyed while acquired; doing so prevents any further use of the Buffer object
- * within the Stream and releases any buffer resources or references held by the Buffer
- * object.
- *
- * If sync support has been enabled for this Stream/Buffer (ie. SyncType is not
- * STREAM_TYPE_NONE), hardware synchronization capabilities may be used to allow hardware
- * operations on a Buffer to still be pending when it is acquired from or released back to
- * libargus. In this case, the returned Buffer will contain the output sync information
- * provided by libargus which the application must obey before accessing the Buffer's
- * image data. Similarly, the application may need to write input sync information to
- * the Buffer before calling releaseBuffer such that libargus will obey the sync before
- * the Buffer is written to by a new capture request. The exact mechanism used for reading
- * and writing this sync state depends on and is documented by the various SyncTypes and
- * their corresponding interfaces.
- *
- * @param[in] timeout The amount of time to allow for the acquire.
- * @param[out] status An optional pointer to return success/status.
- *
- * @returns A Buffer that has been written to by a capture request
- */
- virtual Buffer* acquireBuffer(uint64_t timeout = TIMEOUT_INFINITE, Status* status = NULL) = 0;
-
- /**
- * Release a Buffer back to the stream to make it available for a future capture request.
- *
- * Once a Buffer has been released to the Stream, libargus will have exclusive access to
- * the Buffer's image resources until it is once again acquired by the application via
- * acquireBuffer. Any buffer access outside of libargus during this time may lead to
- * undefined results.
- *
- * While it is often the case that Buffers may be used by libargus in the order they are
- * released, this is not a requirement; libargus may reuse Buffers in any order once they
- * have been released.
- *
- * If sync support has been enabled for this StreamBuffer (ie. SyncType is not
- * STREAM_TYPE_NONE), sync information may need to be written to the Buffer by the client
- * before releaseBuffer is called. The exact mechanism used for writing this sync state
- * depends on and is documented by the various SyncTypes and their corresponding interfaces.
- *
- * Note that while it is safe to destroy a Buffer object while it has been released to
- * libargus, it is possible that pending requests may be using this Buffer and may still
- * output Events that reference the Buffer object, and so the application is responsible
- * for making sure that it does not use any Buffer object that it has previously destroyed.
- * If there are no pending requests using a particular Stream, destroying any of its
- * released Buffers will prevent them from ever being used or returned by libargus again.
- *
- * @param[in] buffer The Buffer to release back to the stream.
- */
- virtual Status releaseBuffer(Buffer* buffer) = 0;
-
- /**
- * Signals the end of the stream.
- *
- * Once the end of stream has been signalled on a stream, any call made to acquireBuffer
- * will immediately (ignoring the timeout parameter) return NULL with a STATUS_END_OF_STREAM
- * status when the following is true:
- * 1) There are no Buffers immediately available to be acquired, and
- * 2) There are no capture requests pending writes to the stream.
- * This implies that no pending or completed frames will be lost, and that all pending or
- * completed frames must be acquired before an END_OF_STREAM status is returned.
- *
- * If any thread is blocked in acquireBuffer when the end of stream is signalled, and the
- * above conditions are met, then that thread will unblock and return END_OF_STREAM immediately.
- */
- virtual Status endOfStream() = 0;
-
- protected:
- ~IBufferOutputStream() {}
- };
-
- /**
- * @class IBuffer
- *
- * Interface that provides the core methods for Buffer objects.
- *
- * @ingroup ArgusBuffer
- */
- DEFINE_UUID(InterfaceID, IID_BUFFER, c723d965,5231,11e7,9598,18,00,20,0c,9a,66);
- class IBuffer : public Interface
- {
- public:
- static const InterfaceID& id() { return IID_BUFFER; }
-
- /**
- * Returns the BufferType of the Buffer.
- */
- virtual BufferType getBufferType() const = 0;
-
- /**
- * Returns the SyncType of the Buffer.
- */
- virtual SyncType getSyncType() const = 0;
-
- /**
- * Sets the client data for the Buffer.
- * This is provided as a convenience for applications to be able to map Buffers to
- * other client-managed data. It is not used at all by the libargus implementation,
- * and is returned as-is by getClientData.
- * Default value: NULL
- *
- * @param[in] clientData The client data pointer to set in the buffer.
- */
- virtual void setClientData(const void* clientData) = 0;
-
- /**
- * Returns the client data from the Buffer.
- */
- virtual const void* getClientData() const = 0;
-
- /**
- * Returns the CaptureMetadata object that was attached to this Buffer when it was last
- * output to the stream from the result of a successful capture request.
- *
- * This method should only ever be called while the Buffer is in an acquired state; ie. the
- * time between when the Buffer was acquired by IBufferOutputStream::acquireBuffer and when
- * it was released by IBufferOutputStream::releaseBuffer. If called outside of the acquired
- * state, NULL will be returned. Similarly, the returned object will only remain valid so
- * long as the Buffer is acquired -- if this object or any of its interfaces are accessed
- * outside of the acquired state, undefined results or abnormal process termination may occur.
- *
- * Metadata will only be written if metadata is enabled for the stream (see
- * IBufferOutputStreamSettings::setMetadataEnable). NULL may also still be returned if there
- * were any capture errors or metadata is otherwise unavailable.
- */
- virtual const CaptureMetadata* getMetadata() const = 0;
-
- protected:
- ~IBuffer() {}
- };
-
- } // namespace Argus
-
- #endif // _ARGUS_BUFFER_STREAM_H
|