IDS peak genericC++ v1.11.1
Loading...
Searching...
No Matches
peak::core::DataStream Class Reference

Represents a GenTL DataStream module. More...

#include <peak/data_stream/peak_data_stream.hpp>

Inheritance diagram for peak::core::DataStream:
peak::core::EventSupportingModule peak::core::Module

Public Types

using BufferRevocationCallback = std::function<void(void* buffer, void* userPtr)>
 

Public Member Functions

 DataStream ()=delete
 
 ~DataStream () override
 
 DataStream (const DataStream &other)=delete
 
DataStream & operator= (const DataStream &other)=delete
 
 DataStream (DataStream &&other)=delete
 
DataStream & operator= (DataStream &&other)=delete
 
std::string Key () const
 Returns the unique key.
 
RawInformation Info (int32_t infoCommand) const
 Delivers information based on the given GenTL info command.
 
std::string ID () const
 Returns the ID.
 
std::string TLType () const
 Returns the TL (transport layer) type.
 
size_t NumBuffersAnnouncedMinRequired () const
 Returns the minimum number of buffers that must be announced before starting the acquisition with StartAcquisition.
 
size_t NumBuffersAnnounced () const
 Retrieves the count of buffers announced via AnnounceBuffer or AllocAndAnnounceBuffer.
 
size_t NumBuffersQueued () const
 Retrieves the count of buffers that are currently queued, i.e., the number of buffers present in the input pool.
 
size_t NumBuffersAwaitDelivery () const
 Retrieves the count of buffers that are currently waiting to be delivered, i.e., the number of buffers present in the output pool.
 
uint64_t NumBuffersDelivered () const
 Retrieves the count of buffers delivered since the last acquisition start.
 
uint64_t NumBuffersStarted () const
 Returns the count of buffers that have been initiated.
 
uint64_t NumUnderruns () const
 Retrieves the count of underruns.
 
size_t NumChunksPerBufferMax () const
 Returns the maximum number of chunks per buffer.
 
size_t BufferAlignment () const
 Returns the buffer alignment.
 
size_t PayloadSize () const
 Returns the payload size in bytes, i.e. the size of the buffers.
 
bool DefinesPayloadSize () const
 Checks whether the data stream defines the payload size.
 
bool IsGrabbing () const
 Checks whether the data stream is grabbing.
 
std::shared_ptr< Device > ParentDevice () const
 Returns the parent device.
 
Buffer Management

std::shared_ptr< Buffer > AnnounceBuffer (void *buffer, size_t size, void *userPtr, const BufferRevocationCallback &revocationCallback)
 Announces a given client allocated buffer to the data stream.
 
std::shared_ptr< Buffer > AllocAndAnnounceBuffer (size_t size, void *userPtr)
 Allocates and announces a producer allocated buffer on the data stream.
 
void QueueBuffer (const std::shared_ptr< Buffer > &buffer)
 Queues a given buffer.
 
void RevokeBuffer (const std::shared_ptr< Buffer > &buffer)
 Revokes a specified buffer.
 
void Flush (DataStreamFlushMode mode)
 Move buffers between the Input Buffer Pool, the Output Buffer Pool and the Announced Buffer Pool, depending on the mode parameter.
 
std::vector< std::shared_ptr< Buffer > > AnnouncedBuffers () const
 Retrieves the list of the currently announced buffers. The buffers' states are irrelevant, as long as they have been announced.
 
Start/Stop Acquisition

void StartAcquisition (AcquisitionStartMode mode=AcquisitionStartMode::Default, uint64_t numToAcquire=INFINITE_NUMBER)
 Starts the acquisition.
 
void StopAcquisition (AcquisitionStopMode mode=AcquisitionStopMode::Default)
 Stops the acquisition.
 
Wait for new buffer

std::shared_ptr< Buffer > WaitForFinishedBuffer (Timeout timeout_ms)
 Blocking wait for a finished Buffer.
 
void KillWait ()
 Tells the data stream to kill one call to WaitForFinishedBuffer.
 
void FlushPendingKillWaits ()
 Flushes the KillWait queue.
 
- Public Member Functions inherited from peak::core::EventSupportingModule
 EventSupportingModule ()=default
 
 ~EventSupportingModule () override=default
 
 EventSupportingModule (const EventSupportingModule &other)=delete
 
EventSupportingModule & operator= (const EventSupportingModule &other)=delete
 
 EventSupportingModule (EventSupportingModule &&other)=delete
 
EventSupportingModule & operator= (EventSupportingModule &&other)=delete
 
std::unique_ptr< EventController > EnableEvents (EventType type)
 Enables events of the given event type.
 
- Public Member Functions inherited from peak::core::Module
 Module ()=default
 
virtual ~Module ()=default
 
 Module (const Module &other)=delete
 
Module & operator= (const Module &other)=delete
 
 Module (Module &&other)=delete
 
Module & operator= (Module &&other)=delete
 
std::vector< std::shared_ptr< NodeMap > > NodeMaps () const
 Returns the module's node maps.
 
std::shared_ptr< class Port > Port () const
 Returns the module's port.
 

Static Public Attributes

static const uint64_t INFINITE_NUMBER = PEAK_INFINITE_NUMBER
 

Detailed Description

Represents a GenTL DataStream module.

This class allows to query information about a GenTL DataStream module and to manage and receive Buffers from the physical device.

The workflow for the buffers follows the GenTL model: First, memory needs to be allocated and announced to the API, so they are in the GenTL "Announced Buffer Pool". Then, the buffers are queued, so they are available in the GenTL "Input Buffer Pool". From this pool, buffers are chosen and filled by the device. Once a buffer is filled, i.e. a new frame is available, it is added to the GenTL "Output Buffer Queue" and a "NewBufferEvent" is sent. At this point, the newly filled buffer is available to the API.

Buffer management

There are two options for managing memory for the buffers:

  • Allocate the memory for the buffer yourself and announce it to the API yourself, using AnnounceBuffer(). Then you'll also need to free the memory for the buffer yourself, once you are done. To help with that, AnnounceBuffer() allows to add a callback, which is called when the buffer is revoked. At that point the memory won't be used anymore, and therefore can be deleted. If you don't add this callback, you'll have to manage the time of deletion yourself.
  • Let the API allocate and free the memory for the buffer, using AllocAndAnnounceBuffer(). Then, the memory will be freed automatically when the buffer is revoked.

After announcing the buffer, use QueueBuffer() to move it to the "Input Buffer Pool".

Once a Buffer is not needed anymore, revoke it using RevokeBuffer().

Use Flush() to move buffers between the Input Buffer Pool, the Output Buffer Queue and the Announced Buffer Pool.

Receiving new buffers

Once enough buffers are announced and queued, use StartAcquisition() to start generating new frames.

Note
Typically, the RemoteDevice also needs to be started using its NodeMap, e.g.:
remoteDevice->NodeMaps()[0]->FindNode<peak::core::nodes::CommandNode>("AcquisitionStart")->Execute();
remoteDevice->NodeMaps()[0]->FindNode<peak::core::nodes::CommandNode>("AcquisitionStart")->WaitUntilDone();
Represents a GenAPI command node.
Definition peak_command_node.hpp:34
@ Default
Definition peak_data_stream.hpp:96

Once the acquisition is started, wait for the NewBufferEvent using WaitForFinishedBuffer(), which blocks until a newly filled buffer is available.

See GenTL Data Stream Module.

Member Typedef Documentation

◆ BufferRevocationCallback

using peak::core::DataStream::BufferRevocationCallback = std::function<void(void* buffer, void* userPtr)>

The type of buffer revocation callbacks.

Constructor & Destructor Documentation

◆ DataStream() [1/3]

peak::core::DataStream::DataStream ( )
delete

◆ ~DataStream()

peak::core::DataStream::~DataStream ( )
inlineoverride

◆ DataStream() [2/3]

peak::core::DataStream::DataStream ( const DataStream & other)
delete

◆ DataStream() [3/3]

peak::core::DataStream::DataStream ( DataStream && other)
delete

Member Function Documentation

◆ AllocAndAnnounceBuffer()

std::shared_ptr< Buffer > peak::core::DataStream::AllocAndAnnounceBuffer ( size_t size,
void * userPtr )
inline

Allocates and announces a producer allocated buffer on the data stream.

The size of this buffer must be equal to the value of the "PayloadSize" node.

To ensure that the payload size does not change while the acquisition is running, it is strongly recommended to set the integer node "TLParamsLocked" in the remote device nodemap to a value of 1. Setting the "TLParamsLocked" node to 1 locks all writable nodes in the XML tree that must not be modified during image acquisition.

Announcing a Buffer to the DataStream will not queue it for use in the acquisition engine. This is a separate step handled by QueueBuffer.

Parameters
[in]sizeThe size of the buffer in bytes to allocate and announce.
[in]userPtrA pointer to user defined data, for identifying the buffer or attaching custom data to the buffer. It is optional (i.e. can be nullptr). See Buffer::UserPtr().
Returns
Proxy to the Buffer that was added to the "Announced Buffer Pool"
Since
1.0
Exceptions
BadAllocExceptionBad memory allocation
BadAccessExceptionThe acquisition has been started and the producer does not support announcing buffers while the acquisition is running.
InternalErrorExceptionAn internal error has occurred.

◆ AnnounceBuffer()

std::shared_ptr< Buffer > peak::core::DataStream::AnnounceBuffer ( void * buffer,
size_t size,
void * userPtr,
const BufferRevocationCallback & revocationCallback )
inline

Announces a given client allocated buffer to the data stream.

The size of this buffer must be equal to the value of the "PayloadSize" node.

To ensure that the payload size does not change while the acquisition is running, it is strongly recommended to set the integer node "TLParamsLocked" in the remote device nodemap to a value of 1. Setting the "TLParamsLocked" node to 1 locks all writable nodes in the XML tree that must not be modified during image acquisition.

Announcing a Buffer to the DataStream will not queue it for use in the acquisition engine. This is a separate step handled by QueueBuffer.

Parameters
[in]bufferThe raw buffer to announce.
[in]sizeThe size in bytes of the raw buffer to announce.
[in]userPtrA pointer to user defined data, for identifying the buffer or attaching custom data to the buffer. Optional (i.e. can be nullptr). See Buffer::UserPtr().
[in]revocationCallbackCallback that is called when this buffer is revoked (via RevokeBuffer()). Use it to handle cleanup of the raw buffer, e.g.:
uint8_t* image_data = new uint8_t[payload_size];
(void)datastream->AnnounceBuffer(image_data, payload_size, nullptr,
[](void* buffer, void* userPtr)
{
delete[] static_cast<uint8_t*>(buffer);
});
Optional (i.e. can be nullptr), if you handle the memory management differently.
Returns
Proxy to the Buffer that was added to the "Announced Buffer Pool"
Since
1.0
Exceptions
InvalidArgumentExceptionOne of the submitted arguments is outside the valid range or is not supported.
BadAccessExceptionThe acquisition has been started and the producer does not support announcing buffers while the acquisition is running.
InternalErrorExceptionAn internal error has occurred.

◆ AnnouncedBuffers()

std::vector< std::shared_ptr< Buffer > > peak::core::DataStream::AnnouncedBuffers ( ) const
inline

Retrieves the list of the currently announced buffers. The buffers' states are irrelevant, as long as they have been announced.

Returns
A list of currently announced buffers.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ BufferAlignment()

size_t peak::core::DataStream::BufferAlignment ( ) const
inline

Returns the buffer alignment.

Returns
Buffer alignment in bytes
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ DefinesPayloadSize()

bool peak::core::DataStream::DefinesPayloadSize ( ) const
inline

Checks whether the data stream defines the payload size.

Returns
True, if the DataStream defines the payload size.
False otherwise. In this case, ask the RemoteDevice for the payload size instead of the DataStream, e.g.:
payload_size =
device->RemoteDevice()->NodeMaps()[0]->FindNode<peak::core::nodes::IntegerNode>("PayloadSize")->Value();
Represents a GenAPI integer node.
Definition peak_integer_node.hpp:37
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ Flush()

void peak::core::DataStream::Flush ( DataStreamFlushMode mode)
inline

Move buffers between the Input Buffer Pool, the Output Buffer Pool and the Announced Buffer Pool, depending on the mode parameter.

Parameters
[in]modeOperation modes being used to flush the buffers of the data stream.
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ FlushPendingKillWaits()

void peak::core::DataStream::FlushPendingKillWaits ( )
inline

Flushes the KillWait queue.

This function clears all queued KillWaits, preventing subsequent calls to DataStream::WaitForFinishedBuffer from throwing a peak::core::AbortedException.

Calls to DataStream::WaitForFinishedBuffer that are currently waiting will be aborted and throw a peak::core::AbortedException.

Note
This function is only available when the acquisition is stopped.
Attention
Any pending new-buffer events will be discarded. Buffers still in the output queue will be moved to a non-queued state, where they will only count as announced and must be requeued. Otherwise, the buffer can not be used by the acquisition engine. To retrieve data from discarded buffers, use Buffer::IsQueued and Buffer::HasNewData to identify them. A buffer discarded by FlushPendingKillWaits is expected to contain new data and return false for Buffer::IsQueued.
Since
1.11
Exceptions
BadAccessExceptionThe acquisition is currently running and needs to be stopped first.
InternalErrorExceptionAn internal error has occurred.

◆ ID()

std::string peak::core::DataStream::ID ( ) const
inline

Returns the ID.

Returns
ID
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ Info()

RawInformation peak::core::DataStream::Info ( int32_t infoCommand) const
inline

Delivers information based on the given GenTL info command.

Parameters
[in]infoCommandThe GenTL info command.

This function can be used to query information going beyond the predefined info functions, based on the GenTL info commands of the corresponding module.

Example (error handling is omitted):

auto info = object->Info(GenTL::XX_INFO_XX);
// Cast depending on the delivered data type
if (info.dataType == GenTL::INFO_DATATYPE_UINT64)
{
uint64_t uint64Var = *reinterpret_cast<const uint64_t*>(info.data.data());
// Do something with the information
}
else if (infoDataTypeVar == GenTL::INFO_DATATYPE_INT64)
{
...
}
...
Returns
Raw information according to the passed info command
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ IsGrabbing()

bool peak::core::DataStream::IsGrabbing ( ) const
inline

Checks whether the data stream is grabbing.

Returns
True, while the acquisition is running.
False, if the acquisition isn't started yet or was stopped.
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ Key()

std::string peak::core::DataStream::Key ( ) const
inline

Returns the unique key.

The returned key is unique even across different producer libraries.

Returns
Unique key
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ KillWait()

void peak::core::DataStream::KillWait ( )
inline

Tells the data stream to kill one call to WaitForFinishedBuffer.

Kills one call to WaitForFinishedBuffer or queues the kill request to be applied to the next call. Each kill results in one call to WaitForFinishedBuffer to be aborted. Calling KillWait multiple times will queue multiple kills. A pending KillWait takes precedence over regular events. This means that if both a new buffer event and a pending KillWait exist, a call to WaitForFinishedBuffer will fail with an AbortedException.

Attention
Pending kills stay queued even if the acquisition is stopped and restarted. They can only be cleared by closing the datastream or calling FlushPendingKillWaits.

To prevent queueing kills, call KillWait only once and only when your acquisition is running. Then, allow the acquisition thread to continue until WaitForFinishedBuffer triggers an AbortedException. You can verify if the acquisition is running by using IsGrabbing.

Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ NumBuffersAnnounced()

size_t peak::core::DataStream::NumBuffersAnnounced ( ) const
inline

Retrieves the count of buffers announced via AnnounceBuffer or AllocAndAnnounceBuffer.

The state or pool of the buffers does not affect the count, as long as they have been announced.

Returns
The number of buffers that have been announced.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ NumBuffersAnnouncedMinRequired()

size_t peak::core::DataStream::NumBuffersAnnouncedMinRequired ( ) const
inline

Returns the minimum number of buffers that must be announced before starting the acquisition with StartAcquisition.

This value is influenced by the "StreamBufferHandlingMode" node in the datastream nodemap.

Returns
The minimum number of announced buffers required.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ NumBuffersAwaitDelivery()

size_t peak::core::DataStream::NumBuffersAwaitDelivery ( ) const
inline

Retrieves the count of buffers that are currently waiting to be delivered, i.e., the number of buffers present in the output pool.

Returns
The number of buffers awaiting delivery.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ NumBuffersDelivered()

uint64_t peak::core::DataStream::NumBuffersDelivered ( ) const
inline

Retrieves the count of buffers delivered since the last acquisition start.

A buffer is considered delivered once it has been retrieved through WaitForFinishedBuffer.

This counter is reset to 0 when a new acquisition is initiated, as described in StartAcquisition.

Returns
The number of buffers delivered since the last acquisition start.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ NumBuffersQueued()

size_t peak::core::DataStream::NumBuffersQueued ( ) const
inline

Retrieves the count of buffers that are currently queued, i.e., the number of buffers present in the input pool.

For additional details, refer to QueueBuffer and WaitForFinishedBuffer.

Returns
The number of buffers currently queued.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ NumBuffersStarted()

uint64_t peak::core::DataStream::NumBuffersStarted ( ) const
inline

Returns the count of buffers that have been initiated.

This counter increases with each new buffer that the acquisition engine begins to fill, regardless of whether the buffer is ultimately discarded or delivered.

The counter starts at 0 when the DataStream is opened and is not reset until the DataStream is closed.

Returns
The total number of buffers that have been initiated.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ NumChunksPerBufferMax()

size_t peak::core::DataStream::NumChunksPerBufferMax ( ) const
inline

Returns the maximum number of chunks per buffer.

Returns
Maximum number of chunks per buffer
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ NumUnderruns()

uint64_t peak::core::DataStream::NumUnderruns ( ) const
inline

Retrieves the count of underruns.

This counter increments when the acquisition engine has no buffers queued (see QueueBuffer) and a new frame is received from the remote device. As a result, the acquisition engine discards the incoming data because there is no available buffer to store it.

If you encounter this situation, verify that you are calling QueueBuffer and ensure the time between receiving the buffer through WaitForFinishedBuffer and calling QueueBuffer is less than the time required to capture a frame (1 / frame rate).

This counter is reset to zero at the time the DataStream is opened using DataStreamDescriptor::OpenDataStream.

Returns
The number of underruns.
Since
1.0
Exceptions
InternalErrorExceptionIf an internal error occurs.

◆ operator=() [1/2]

DataStream & peak::core::DataStream::operator= ( const DataStream & other)
delete

◆ operator=() [2/2]

DataStream & peak::core::DataStream::operator= ( DataStream && other)
delete

◆ ParentDevice()

std::shared_ptr< Device > peak::core::DataStream::ParentDevice ( ) const
inline

Returns the parent device.

Returns
Parent device
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ PayloadSize()

size_t peak::core::DataStream::PayloadSize ( ) const
inline

Returns the payload size in bytes, i.e. the size of the buffers.

Returns
Payload size in bytes
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ QueueBuffer()

void peak::core::DataStream::QueueBuffer ( const std::shared_ptr< Buffer > & buffer)
inline

Queues a given buffer.

Queueing a given buffer makes it available to be used by the acquisition engine for receiving new data.

Parameters
[in]bufferThe buffer to queue.
Since
1.0
Exceptions
InvalidArgumentExceptionOne of the submitted arguments is outside the valid range or is not supported.
InternalErrorExceptionAn internal error has occurred.

◆ RevokeBuffer()

void peak::core::DataStream::RevokeBuffer ( const std::shared_ptr< Buffer > & buffer)
inline

Revokes a specified buffer.

This function revokes the given buffer. If the buffer was allocated by the client, the callback provided during the buffer announcement (AnnounceBuffer) will be triggered.

Note
A buffer can only be revoked if it is not queued, meaning it is neither in the input nor the output pool.

You can use the Flush function with DataStreamFlushMode::DiscardAll as the flush mode to ensure that all buffers are safe to be revoked.

Parameters
[in]bufferThe buffer to revoke.
Since
1.0
Exceptions
InvalidArgumentExceptionIf one of the provided arguments is outside the valid range or unsupported.
InternalErrorExceptionIf an internal error occurs.

◆ StartAcquisition()

void peak::core::DataStream::StartAcquisition ( AcquisitionStartMode mode = AcquisitionStartMode::Default,
uint64_t numToAcquire = INFINITE_NUMBER )
inline

Starts the acquisition.

Starts the acquisition engine on the host side. The acquisition on the remote device needs to be started separately using the "AcquisitionStart" command node.

The acquisition engine depends on the payload size value not changing between announcing the buffers to the data stream and while the acquisition is running. For information on how to ensure this can't happen, see AnnounceBuffer.

Parameters
[in]modeThe mode being used to start the acquisition.
[in]numToAcquireThe number of buffers to acquire.
Since
1.0
Exceptions
BadAccessExceptionThe acquisition is already running
InternalErrorExceptionAn internal error has occurred.

◆ StopAcquisition()

void peak::core::DataStream::StopAcquisition ( AcquisitionStopMode mode = AcquisitionStopMode::Default)
inline

Stops the acquisition.

Parameters
[in]modeThe mode being used to stop the acquisition.
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ TLType()

std::string peak::core::DataStream::TLType ( ) const
inline

Returns the TL (transport layer) type.

Returns
TL type
Since
1.0
Exceptions
InternalErrorExceptionAn internal error has occurred.

◆ WaitForFinishedBuffer()

std::shared_ptr< Buffer > peak::core::DataStream::WaitForFinishedBuffer ( Timeout timeout_ms)
inline

Blocking wait for a finished Buffer.

Block and wait for the next buffer to be received or until the supplied timeout is exceeded. In order to wait indefinitely use INFINITE_TIMEOUT.

A call to WaitForFinishedBuffer can be aborted immediately and at any time by calling KillWait from another thread, resulting in an AbortedException being thrown. This is especially useful when using INFINITE_TIMEOUT.

A buffer returned by WaitForFinishedBuffer is guaranteed to remain untouched by the acquisition engine, until it has been re-queued using QueueBuffer. Depending on the time it takes the application to process the image, it may be beneficial to copy the buffer data, re-queue the buffer and to process the copy.

Attention
If buffers are not re-queued using QueueBuffer in time and no more buffers are available to the acquisition engine, no buffers will be received and image data will be discarded! For more information see NumUnderruns.
Parameters
[in]timeout_msThe time to wait for a finished buffer in milliseconds. Use DataStream::INFINITE_NUMBER to wait indefinitely.
Returns
Newly filled Buffer.
Since
1.0
Exceptions
AbortedExceptionThe wait was aborted by KillWait or FlushPendingKillWaits
TimeoutExceptionThe function call timed out
InternalErrorExceptionAn internal error has occurred.

Member Data Documentation

◆ INFINITE_NUMBER

const uint64_t peak::core::DataStream::INFINITE_NUMBER = PEAK_INFINITE_NUMBER
static

The constant defining an infinite number, used in StartAcquisition().


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