![]() |
IDS peak genericC++ v1.11.1
|
Represents a GenTL DataStream module. More...
#include <peak/data_stream/peak_data_stream.hpp>
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 |
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.
There are two options for managing memory for the buffers:
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.
Once enough buffers are announced and queued, use StartAcquisition() to start generating new frames.
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.
| using peak::core::DataStream::BufferRevocationCallback = std::function<void(void* buffer, void* userPtr)> |
The type of buffer revocation callbacks.
|
delete |
|
inlineoverride |
|
delete |
|
delete |
|
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.
| [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(). |
| BadAllocException | Bad memory allocation |
| BadAccessException | The acquisition has been started and the producer does not support announcing buffers while the acquisition is running. |
| InternalErrorException | An internal error has occurred. |
|
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.
| [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);
});
|
| InvalidArgumentException | One of the submitted arguments is outside the valid range or is not supported. |
| BadAccessException | The acquisition has been started and the producer does not support announcing buffers while the acquisition is running. |
| InternalErrorException | An internal error has occurred. |
|
inline |
Retrieves the list of the currently announced buffers. The buffers' states are irrelevant, as long as they have been announced.
| InternalErrorException | If an internal error occurs. |
|
inline |
Returns the buffer alignment.
| InternalErrorException | An internal error has occurred. |
|
inline |
Checks whether the data stream defines the payload size.
| InternalErrorException | An internal error has occurred. |
|
inline |
Move buffers between the Input Buffer Pool, the Output Buffer Pool and the Announced Buffer Pool, depending on the mode parameter.
| [in] | mode | Operation modes being used to flush the buffers of the data stream. |
| InternalErrorException | An internal error has occurred. |
|
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.
false for Buffer::IsQueued. | BadAccessException | The acquisition is currently running and needs to be stopped first. |
| InternalErrorException | An internal error has occurred. |
|
inline |
|
inline |
Delivers information based on the given GenTL info command.
| [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):
| InternalErrorException | An internal error has occurred. |
|
inline |
Checks whether the data stream is grabbing.
| InternalErrorException | An internal error has occurred. |
|
inline |
Returns the unique key.
The returned key is unique even across different producer libraries.
| InternalErrorException | An internal error has occurred. |
|
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.
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.
| InternalErrorException | An internal error has occurred. |
|
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.
| InternalErrorException | If an internal error occurs. |
|
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.
| InternalErrorException | If an internal error occurs. |
|
inline |
Retrieves the count of buffers that are currently waiting to be delivered, i.e., the number of buffers present in the output pool.
| InternalErrorException | If an internal error occurs. |
|
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.
| InternalErrorException | If an internal error occurs. |
|
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.
| InternalErrorException | If an internal error occurs. |
|
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.
| InternalErrorException | If an internal error occurs. |
|
inline |
Returns the maximum number of chunks per buffer.
| InternalErrorException | An internal error has occurred. |
|
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.
| InternalErrorException | If an internal error occurs. |
|
delete |
|
delete |
|
inline |
Returns the parent device.
| InternalErrorException | An internal error has occurred. |
|
inline |
Returns the payload size in bytes, i.e. the size of the buffers.
| InternalErrorException | An internal error has occurred. |
|
inline |
Queues a given buffer.
Queueing a given buffer makes it available to be used by the acquisition engine for receiving new data.
| [in] | buffer | The buffer to queue. |
| InvalidArgumentException | One of the submitted arguments is outside the valid range or is not supported. |
| InternalErrorException | An internal error has occurred. |
|
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.
You can use the Flush function with DataStreamFlushMode::DiscardAll as the flush mode to ensure that all buffers are safe to be revoked.
| [in] | buffer | The buffer to revoke. |
| InvalidArgumentException | If one of the provided arguments is outside the valid range or unsupported. |
| InternalErrorException | If an internal error occurs. |
|
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.
| [in] | mode | The mode being used to start the acquisition. |
| [in] | numToAcquire | The number of buffers to acquire. |
| BadAccessException | The acquisition is already running |
| InternalErrorException | An internal error has occurred. |
|
inline |
Stops the acquisition.
| [in] | mode | The mode being used to stop the acquisition. |
| InternalErrorException | An internal error has occurred. |
|
inline |
Returns the TL (transport layer) type.
| InternalErrorException | An internal error has occurred. |
|
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.
| [in] | timeout_ms | The time to wait for a finished buffer in milliseconds. Use DataStream::INFINITE_NUMBER to wait indefinitely. |
| AbortedException | The wait was aborted by KillWait or FlushPendingKillWaits |
| TimeoutException | The function call timed out |
| InternalErrorException | An internal error has occurred. |
|
static |
The constant defining an infinite number, used in StartAcquisition().