Libargus API Libargus Camera API

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

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Public Member Functions | Static Public Member Functions | Protected Member Functions
Argus::IBufferOutputStream Class Reference
BufferOutputStream

Interface that provides the methods used with Buffer-based OutputStreams. More...

`#include <BufferStream.h>`

Inheritance diagram for Argus::IBufferOutputStream:

List of all members.

## Public Member Functions
virtual BufferType | getBufferType () const =0
| Returns the BufferType of the stream.
virtual SyncType | getSyncType () const =0
virtual BufferSettings * | createBufferSettings (Status *status=NULL)=0
| Creates a BufferSettings object.
virtual Buffer * | createBuffer (const BufferSettings *settings, Status *status=NULL)=0
| Creates a Buffer object.
virtual Buffer * | acquireBuffer (uint64_t timeout=TIMEOUT_INFINITE, Status *status=NULL)=0
| Acquires a Buffer from the stream that was written to by a libargus capture request.
virtual Status | releaseBuffer (Buffer *buffer)=0
| Release a Buffer back to the stream to make it available for a future capture request.
virtual Status | endOfStream ()=0
| Signals the end of the stream.

## Static Public Member Functions
static const InterfaceID & | id ()

## Protected Member Functions
| ~IBufferOutputStream ()
Protected Member Functions inherited from Argus::Interface
| Interface ()
| ~Interface ()

## Detailed Description

Interface that provides the methods used with Buffer-based OutputStreams.

Definition at line 221 of file BufferStream.h.

## Constructor & Destructor Documentation

Argus::IBufferOutputStream::~IBufferOutputStream | ( |  | ) |
| inline protected

Definition at line 343 of file BufferStream.h.

## Member Function Documentation

virtual Buffer* Argus::IBufferOutputStream::acquireBuffer | ( | uint64_t | timeout = `TIMEOUT_INFINITE`,
|  | Status * | status = `NULL`
| ) |  |
| pure virtual

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.

Parameters:

  [in] | timeout | The amount of time to allow for the acquire.
  [out] | status | An optional pointer to return success/status.

Returns:
  A Buffer that has been written to by a capture request

virtual Buffer* Argus::IBufferOutputStream::createBuffer | ( | const BufferSettings * | settings,
|  | Status * | status = `NULL`
| ) |  |
| pure virtual

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.

Parameters:

  [in] | settings | the buffer settings to use for Buffer creation.
  [out] | status | An optional pointer to return success/status.

Returns:
  a new BufferSettings, or NULL on failure (error code written to 'status').

virtual BufferSettings* Argus::IBufferOutputStream::createBufferSettings | ( | Status * | status = `NULL` | ) |
| pure virtual

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.

Parameters:

  [out] | status | An optional pointer to return success/status.

Returns:
  a new BufferSettings, or NULL on failure (error code written to 'status').

virtual Status Argus::IBufferOutputStream::endOfStream | ( |  | ) |
| pure virtual

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 BufferType Argus::IBufferOutputStream::getBufferType | ( |  | ) | const
| pure virtual

Returns the BufferType of the stream.

virtual SyncType Argus::IBufferOutputStream::getSyncType | ( |  | ) | const
| pure virtual

Returns:
  the SyncType of the stream.

static const InterfaceID& Argus::IBufferOutputStream::id | ( |  | ) |
| inline static

Definition at line 224 of file BufferStream.h.

virtual Status Argus::IBufferOutputStream::releaseBuffer | ( | Buffer * | buffer | ) |
| pure virtual

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.

Parameters:

  [in] | buffer | The Buffer to release back to the stream.

The documentation for this class was generated from the following file:

- include/Argus/BufferStream.h