Represents a GenTL DataStream module. More...

#include <peak/data_stream/peak_data_stream.hpp>

Inheritance diagram for peak::core::DataStream:

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 announced buffers required to start the acquisition.

size_t	NumBuffersAnnounced () const
	Returns the number of announced buffers.

size_t	NumBuffersQueued () const
	Returns the number of queued buffers.

size_t	NumBuffersAwaitDelivery () const
	Returns the number of buffers awaiting delivery.

uint64_t	NumBuffersDelivered () const
	Returns the number of delivered buffers.

uint64_t	NumBuffersStarted () const
	Returns the number of started buffers.

uint64_t	NumUnderruns () const
	Returns the number 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 given buffer.

void	Flush (DataStreamFlushMode mode)
	Move buffers between the Input Buffer Pool, the Output Buffer Queue and the Announced Buffer Pool, depending on the mode parameter.

std::vector< std::shared_ptr< Buffer > >	AnnouncedBuffers () const
	Returns the currently announced buffers.

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 a wait for a finished buffer.

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

Additional Inherited Members

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.:
stream->StartAcquisition(peak::core::AcquisitionStartMode::Default);

remoteDevice->NodeMaps()[0]->FindNode<peak::core::nodes::CommandNode>("AcquisitionStart")->Execute();

remoteDevice->NodeMaps()[0]->FindNode<peak::core::nodes::CommandNode>("AcquisitionStart")->WaitUntilDone();

peak::core::nodes::CommandNode
Represents a GenAPI command node.
Definition peak_command_node.hpp:33

peak::core::AcquisitionStartMode::Default
@ Default

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" 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.

Parameters

[in]	size	The size of the buffer in bytes to allocate and announce.
[in]	userPtr	A 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: Buffer proxy

Since: 1.0

Exceptions

BadAllocException	Bad memory allocation
InternalErrorException	An 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" 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.

Parameters

[in]	buffer	The raw buffer to announce.
[in]	size	The size in bytes of the raw buffer to announce.
[in]	userPtr	A 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]	revocationCallback	Callback 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: Buffer proxy

Since: 1.0

Exceptions

InvalidArgumentException	One of the submitted arguments is outside the valid range or is not supported.
InternalErrorException	An internal error has occurred.

◆ AnnouncedBuffers()

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

inline

Returns the currently announced buffers.

Returns: List of currently announced buffers

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ BufferAlignment()

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

inline

Returns the buffer alignment.

Returns: Buffer alignment in bytes

Since: 1.0

Exceptions

InternalErrorException An 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();

peak::core::nodes::IntegerNode
Represents a GenAPI integer node.
Definition peak_integer_node.hpp:36

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ Flush()

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

inline

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

Parameters

[in] mode Operation modes being used to flush the buffers of the data stream.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ ID()

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

inline

Returns the ID.

Returns: ID

Since: 1.0

Exceptions

InternalErrorException An 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] infoCommand The 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):

#include <peak/thirdparty/GenTL.h>
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

InternalErrorException An 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

InternalErrorException An 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

InternalErrorException An internal error has occurred.

◆ KillWait()

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

inline

Tells the data stream to kill a wait for a finished buffer.

Kills one call to WaitForFinishedBuffer or queues the kill request to be applied to the next call to WaitForFinishedBuffer immediately.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ NumBuffersAnnounced()

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

inline

Returns the number of announced buffers.

Returns: Number of announced buffers

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ NumBuffersAnnouncedMinRequired()

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

inline

Returns the minimum number of announced buffers required to start the acquisition.

Returns: Minimum number of announced buffers required

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ NumBuffersAwaitDelivery()

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

inline

Returns the number of buffers awaiting delivery.

Returns: Number of buffers awaiting delivery

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ NumBuffersDelivered()

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

inline

Returns the number of delivered buffers.

Returns: Number of delivered buffers

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ NumBuffersQueued()

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

inline

Returns the number of queued buffers.

Returns: Number of queued buffers

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ NumBuffersStarted()

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

inline

Returns the number of started buffers.

Returns: Number of started buffers

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ 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

InternalErrorException An internal error has occurred.

◆ NumUnderruns()

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

inline

Returns the number of underruns.

Returns: Number of underruns

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ 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

InternalErrorException An 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

InternalErrorException An 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] buffer The buffer to queue.

Since: 1.0

Exceptions

InvalidArgumentException	One of the submitted arguments is outside the valid range or is not supported.
InternalErrorException	An internal error has occurred.

◆ RevokeBuffer()

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

inline

Revokes a given buffer.

This function revokes a given buffer. If the given buffer was allocated by the client side, the callback given during buffer announcement (AnnounceBuffer()) gets triggered.

Parameters

[in] buffer The buffer to revoke.

Since: 1.0

Exceptions

InvalidArgumentException	One of the submitted arguments is outside the valid range or is not supported.
InternalErrorException	An internal error has occurred.

◆ 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]	mode	The mode being used to start the acquisition.
[in]	numToAcquire	The number of buffers to acquire.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ StopAcquisition()

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

inline

Stops the acquisition.

Parameters

[in] mode The mode being used to stop the acquisition.

Since: 1.0

Exceptions

InternalErrorException An 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

InternalErrorException An 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.

Additionally the blocking wait can be aborted by calling KillWait.

Note: After the buffer has been received it has to be requeued using QueueBuffer once the buffer data has been copied or processed. Until the buffer is requeued it is not available to the acquisition engine. Once the acquisition engine runs out of buffers no more images can be received.

Parameters

[in] timeout_ms The time to wait for a finished buffer in milliseconds. Use DataStream::INFINITE_NUMBER to wait indefinitely.

Returns: Newly filled Buffer.

Since: 1.0

Exceptions

AbortedException	The wait was aborted
TimeoutException	The function call timed out
InternalErrorException	An 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:

peak/data_stream/peak_data_stream.hpp

Public Types

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Buffer management

Receiving new buffers

Member Typedef Documentation

◆ BufferRevocationCallback

Constructor & Destructor Documentation

◆ DataStream() [1/3]

◆ ~DataStream()

◆ DataStream() [2/3]

◆ DataStream() [3/3]

Member Function Documentation

◆ AllocAndAnnounceBuffer()

◆ AnnounceBuffer()

◆ AnnouncedBuffers()

◆ BufferAlignment()

◆ DefinesPayloadSize()

◆ Flush()

◆ ID()

◆ Info()

◆ IsGrabbing()

◆ Key()

◆ KillWait()

◆ NumBuffersAnnounced()

◆ NumBuffersAnnouncedMinRequired()

◆ NumBuffersAwaitDelivery()

◆ NumBuffersDelivered()

◆ NumBuffersQueued()

◆ NumBuffersStarted()

◆ NumChunksPerBufferMax()

◆ NumUnderruns()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ParentDevice()

◆ PayloadSize()

◆ QueueBuffer()

◆ RevokeBuffer()

◆ StartAcquisition()

◆ StopAcquisition()

◆ TLType()

◆ WaitForFinishedBuffer()

Member Data Documentation

◆ INFINITE_NUMBER