Pylon::IStreamGrabber#

Module: Low Level API

Low Level API: Interface to an (input) data stream. More…

#include <pylon/StreamGrabber.h>

Public Functions#

Detailed Description#

class Pylon::IStreamGrabber;

Low Level API: Interface to an (input) data stream.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Attention: The Low Level API has been deprecated in pylon 6.0. It is recommended to use the Instant Camera classes instead.

Public Functions Documentation#

function Open#

virtual void Open() =0

Opens the stream grabber.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The corresponding device is open.
• The stream grabber is closed.

Postcondition:

• The stream grabber is open.
• If the device is closed while the stream grabber is open, the stream grabber is closed automatically.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber is already open or prepared. The stream grabber remains in the same state after raising the exception in this case.
• Throws an exception if the stream grabber is closed and opening the stream grabber fails. The stream grabber remains closed after raising the exception.

function Close#

virtual void Close() =0

Closes the stream grabber.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Postcondition:

• Any running grab has been stopped by calling FinishGrab().
• The stream grabber is closed.
• All results waiting in the output queue are discarded.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

Does not throw C++ exceptions.

This method calls FinishGrab() automatically if needed.

function IsOpen#

virtual bool IsOpen() const =0

Retrieve whether the stream grabber is open.

Return: Returns true if the stream grabber is open.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Thread Safety:

This method can be synchronized using an internal stream grabber lock.

Error Safety:

Does not throw C++ exceptions.

function RegisterBuffer#

virtual StreamBufferHandle RegisterBuffer(
    void * pBuffer,
    size_t bufferSize
) =0

Registers a buffer for subsequent use.

Parameters:

• pBuffer The pointer of the buffer that is to be used for grabbing e.g., for grabbing images.
• bufferSize The size of the provided buffer in bytes.

Return: Returns a handle for the registered buffer that can be used in subsequent calls.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• pBuffer must not be NULL.
• The buffer size must not exceed the value of the node map integer parameter MaxBufferSize specified when PrepareGrab was called.
• Less buffers are already registered than value of the node map integer parameter MaxNumBuffer specified when PrepareGrab was called.
• The stream grabber is prepared, see PrepareGrab().
• The buffer has not been registered already.

Postcondition:

• The buffer is registered.
• Transport Layer specific preparations have been executed e.g., locking the memory pages of the buffer.
• The buffer must not be freed while being registered.
• If the stream grabber requires the additional streaming state, streaming must not be started, see IsStartAndStopStreamingMandatory() and StartStreamingIfMandatory().

Thread Safety:

This method can be synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if registering the buffer fails. The buffer is not registered after raising an exception.

function DeregisterBuffer#

virtual const void * DeregisterBuffer(
    StreamBufferHandle hStreamBuffer
) =0

Deregisters the buffer.

Parameters:

• hStreamBuffer The handle of a buffer that has been provided by RegisterBuffer()

Return: Returns the pointer of the corresponding buffer.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The buffer is registered.
• The buffer is not queued. Either it has not been queued yet, see QueueBuffer(), or it has been retrieved after grabbing using RetrieveResult().
• FinishGrab() or Close() have not been called for the grab session yet.
• If the stream grabber requires the additional streaming state, streaming must not be started, see IsStartAndStopStreamingMandatory() and StartStreamingIfMandatory().

Postcondition:

• Transport layer-specific preparations have been reversed.
• The buffer is deregistered.
• The buffer can be freed if needed e.g., by calling delete.

Error Safety:

Throws an exception if deregistering the buffer fails.

function PrepareGrab#

virtual void PrepareGrab() =0

Prepares grabbing.

Note

• Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.
• pylon uses a pool of buffers with a fixed amount of buffers to grab images. This is required because certain preparations e.g., locking the buffer's memory pages, must be made by the driver to be able to grab images into a buffer. Thus, using a pool of buffers is much more efficient than allocating a new buffer for every grabbed image.
• There can be limitations depending on the transport layer technology used when using a large amount of buffers.

Precondition:

• The node map integer parameter MaxBufferSize is set, see GetNodeNap().
• The node map integer parameter MaxNumBuffer is set, see GetNodeNap().
• The stream grabber is open.
• No grab session is currently in progress.

Postcondition:

• Resources required for grabbing are allocated.
• The camera is set up for grabbing.
• Critical camera parameters, provided by IPylonDevice::GetNodeMap(), are locked.
• The stream grabber is prepared.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if preparing the stream grabber fails. The stream grabber is not prepared after raising the exception.

The node map integer parameters MaxBufferSize and MaxNumBuffer need to be set before calling PrepareGrab().

MaxNumBuffer should be set to the number of buffers you plan to use for grabbing. MaxBufferSize needs to be set according to the PayloadSize parameter of the camera device or the stream grabber. If the stream grabber provides a PayloadSize parameter, the MaxBufferSize must be at least the size reported by the stream grabber payload size. This is the case if for instance a frame grabber or additional preprocessing is used. If the stream grabber does not provide a PayloadSize parameter, the MaxBufferSize must be at least the size reported by the camera device PayloadSize parameter.

function IsStartAndStopStreamingMandatory#

virtual bool IsStartAndStopStreamingMandatory() =0

Returns true if the Stream Grabber requires calling StartStreamingIfMandatory() for operation.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

Does not throw C++ exceptions.

function StartStreamingIfMandatory#

virtual void StartStreamingIfMandatory() =0

Starts streaming for the stream grabber if this is mandatory for operation.

Note

• Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.
• This method has been added in pylon 6.0 for supporting CoaXPress. Prior implementations of pylon stream grabbers did not require calling start and stop streaming. The IsStartAndStopStreamingMandatory(), StartStreamingIfMandatory(), and StopStreamingIfMandatory() methods allow backward-compatible operation.

Precondition:

• The stream grabber is prepared.

Postcondition:

• If the stream grabber does not require StartStreamingIfMandatory(), nothing is done.
• Streaming is started. For GenTL-based stream grabbers DSStartAcquistion is called

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if start streaming fails. The stream grabber is not streaming after raising the exception.

Some stream grabbers e.g., some stream grabbers based on GenTL, have limitations on when buffers can be registered. For these stream grabbers it is mandatory to register all buffers first and call StartStreamingIfMandatory() aftwards. Between the StartStreamingIfMandatory() and StopStreamingIfMandatory() calls no buffers can be registered or deregistered if such a limitation exists.

function StopStreamingIfMandatory#

virtual void StopStreamingIfMandatory() =0

Stops streaming for the stream grabber if this is mandatory for operation.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The stream grabber is in streaming mode if start and stop streaming is mandatory.

Postcondition:

• If the stream grabber does not require StopStreamingIfMandatory(), nothing is done.
• Streaming is stopped. For GenTL-based stream grabbers DSStopAcquistion is called.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if stop streaming fails. The stream grabber is not streaming after raising the exception.

Some stream grabbers e.g., some stream grabbers based on GenTL, have limitations on when buffers can be registered. For these stream grabbers it is mandatory to call StopStreamingIfMandatory to be able to deregister buffer afterwards.

function FinishGrab#

virtual void FinishGrab() =0

Stops grabbing finally.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The stream grabber is prepared.

Postcondition:

• Resources required for grabbing are freed.
• The camera is not set up for grabbing anymore
• Critical camera parameters, provided by IPylonDevice::GetNodeMap(), are unlocked.
• The stream grabber is open.
• Queued buffers are available in the output queue of the stream grabber and can be retrieved calling RetrieveResult().
• All buffers are deregistered.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if finishing the grab fails. The stream grabber is in open state after raising the exception.

This method calls FlushBuffersToOutput() automatically if needed.

function QueueBuffer#

virtual void QueueBuffer(
    StreamBufferHandle hStreamBuffer,
    const void * pContext =NULL
) =0

Enqueues a buffer in the input queue.

Parameters:

• hStreamBuffer The handle of a buffer that has been provided by RegisterBuffer().
• pContext A user-provided pointer passed along with buffer in the internal input and output queues.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The buffer is registered, see RegisterBuffer().
• The stream grabber is prepared.
• The buffer has not been queued for grabbing yet.
• The buffer is not waiting in the output queue of the stream grabber. The buffer can be queued again after it has been retrieved using RetrieveResult().

Postcondition:

• The buffer is queued to input queue of the stream grabber.
• The buffer cannot be deregistered until it has been retrieved using RetrieveResult().

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if queuing the buffer fails.

function FlushBuffersToOutput#

virtual void FlushBuffersToOutput() =0

Cancels grabbing the current buffer and flushes all buffers to the output queue.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The stream grabber is prepared.

Postcondition:

• All queued buffers are placed in the output queue of the stream grabber and can be retrieved using RetrieveResult().
• Buffers that have not been grabbed completely before calling FlushBuffersToOutput are marked with the EGrabStatus Canceled.
• The stream grabber is prepared.
• Buffers can be queued again to continue grabbing.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if canceling the grab fails.

function CancelGrab#

virtual void CancelGrab() =0

This method has been renamed to FlushBuffersToOutput(). Calling CancelGrab calls FlushBuffersToOutput();.

function RetrieveResult#

virtual bool RetrieveResult(
    GrabResult & grabResult
) =0

Retrieves one grab result from the output queue.

Return: Returns true when result was available.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Precondition:

• The stream grabber is open.

Postcondition:

• If a grab result was available, it has been removed from the ouput queue.
• The corresponding buffer can be queued again for grabbing.

Thread Safety:

This method is synchronized using an internal stream grabber lock.

Error Safety:

• Throws a LogicalErrorException if the stream grabber state does not match the preconditions.
• Throws an exception if retrieving the result fails. This does not change the stream grabber state.

param[out] grabResult The object the grab result data is returned in if true is returned. The grabResult remains unchanged if false is returned.

function GetWaitObject#

virtual WaitObject & GetWaitObject() const =0

Returns the result event object of the stream grabber.

Return: Returns the result event object of the stream grabber.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Thread Safety:

This method can be synchronized using an internal stream grabber lock.

Error Safety:

Does not throw C++ exceptions.

This object is associated with the output queue of the stream grabber. The event is signaled when output queue is non-empty.

function GetNodeMap#

virtual GenApi::INodeMap * GetNodeMap() =0

Returns the associated stream grabber parameters.

Return: Returns the associated stream grabber parameters. The returned pointer is never NULL.

Note Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects. If you want to control which buffers are used for grabbing, you can use the Pylon::IBufferFactory.

Thread Safety:

This method can be synchronized using an internal stream grabber lock.

Error Safety:

Does not throw C++ exceptions.