Pylon Logo Basler Logo
List of all members
Pylon::CStreamGrabberProxyT< TParams > Class Template Reference

Low Level API: The stream grabber class with parameter access methods. More...

#include <pylon/StreamGrabberProxy.h>

Inheritance diagram for Pylon::CStreamGrabberProxyT< TParams >:
Inheritance graph
[legend]

Public Member Functions

Construction
 CStreamGrabberProxyT ()
 Creates a CStreamGrabberProxyT object that is not attached to a pylon stream grabber. Use the Attach() method to attach the pylon stream grabber.
 
 CStreamGrabberProxyT (Pylon::IStreamGrabber *)
 Creates a CStreamGrabberProxyT object and attaches it to a pylon stream grabber.
 
virtual ~CStreamGrabberProxyT ()
 Destructor.
 
Some smart pointer functionality
virtual void Attach (IStreamGrabber *)
 Attach a pylon stream grabber.
 
virtual bool IsAttached () const
 Checks if a pylon stream grabber is attached.
 
virtual IStreamGrabberGetStreamGrabber () const
 Returns the pylon stream grabber interface pointer.
 
Implementation of the IStreamGrabber interface

See Pylon::IStreamGrabber for more details.

void Open ()
 Opens the stream grabber. More...
 
void Close ()
 Closes the stream grabber. More...
 
bool IsOpen () const
 Retrieve whether the stream grabber is open. More...
 
StreamBufferHandle RegisterBuffer (void *pBuffer, size_t bufferSize)
 Registers a buffer for subsequent use. More...
 
const void * DeregisterBuffer (StreamBufferHandle hStreamBuffer)
 Deregisters the buffer. More...
 
void PrepareGrab ()
 Prepares grabbing. More...
 
bool IsStartAndStopStreamingMandatory ()
 Returns true if the Stream Grabber requires calling StartStreamingIfMandatory() for operation. More...
 
void StartStreamingIfMandatory ()
 Starts streaming for the stream grabber if this is mandatory for operation. More...
 
void StopStreamingIfMandatory ()
 Stops streaming for the stream grabber if this is mandatory for operation. More...
 
void FinishGrab ()
 Stops grabbing finally. More...
 
void QueueBuffer (StreamBufferHandle hStreamBuffer, const void *pContext=NULL)
 Enqueues a buffer in the input queue. More...
 
void FlushBuffersToOutput ()
 Cancels grabbing the current buffer and flushes all buffers to the output queue. More...
 
void CancelGrab ()
 
bool RetrieveResult (GrabResult &Result)
 Retrieves one grab result from the output queue. More...
 
WaitObjectGetWaitObject () const
 Returns the result event object of the stream grabber. More...
 
GenApi::INodeMapGetNodeMap ()
 Returns the associated stream grabber parameters. More...
 
Some smart pointer functionality
virtual void Attach (GenApi::INodeMap *, bool replace=false)
 Attach a pylon node map.
 
virtual GenApi::INodeMapGetNodeMap () const
 Returns the pylon node map interface pointer.
 
Partial implementation of the INodeMap interface

See GENAPI_NAMESPACE::INodeMap for more details

void GetNodes (GenApi::NodeList_t &Nodes) const
 Retrieves all nodes in the node map. More...
 
GenApi::INodeGetNode (const GenICam::gcstring &Name) const
 Retrieves the node from the central map by Name. More...
 
void InvalidateNodes () const
 Invalidates all nodes. More...
 
void Poll (int64_t ElapsedTime)
 Fires nodes which have a polling time. More...
 

Detailed Description

template<class TParams>
class Pylon::CStreamGrabberProxyT< TParams >

Low Level API: The stream grabber class with parameter access methods.

This is the base class for pylon stream grabber providing access to configuration parameters.

See also
Accessing Parameters
Template Parameters
TParamsThe specific parameter class (auto generated from the parameter xml file)

Member Function Documentation

template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::Close ( void  )
inline

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.

This method calls FinishGrab() automatically if needed.

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.
template<class TParams >
const void* Pylon::CStreamGrabberProxyT< TParams >::DeregisterBuffer ( StreamBufferHandle  hStreamBuffer)
inline

Deregisters the 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.
Parameters
[in]hStreamBufferThe handle of a buffer that has been provided by RegisterBuffer()
Returns
Returns the pointer of the corresponding buffer.
Precondition
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.
template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::FinishGrab ( )
inline

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.

This method calls FlushBuffersToOutput() automatically if needed.

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.
template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::FlushBuffersToOutput ( )
inline

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.
template<class TParams >
GenApi::INode* Pylon::CNodeMapProxyT< TParams >::GetNode ( const GenICam::gcstring Name) const
inlineinherited

Retrieves the node from the central map by Name.

template<class TParams >
GenApi::INodeMap* Pylon::CStreamGrabberProxyT< TParams >::GetNodeMap ( void  )
inline

Returns the associated stream grabber parameters.

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.
Returns
Returns the associated stream grabber parameters. The returned pointer is never NULL.
Thread Safety:
This method can be synchronized using an internal stream grabber lock.
Error Safety:
Does not throw C++ exceptions.
template<class TParams >
void Pylon::CNodeMapProxyT< TParams >::GetNodes ( GenApi::NodeList_t Nodes) const
inlineinherited

Retrieves all nodes in the node map.

template<class TParams >
WaitObject& Pylon::CStreamGrabberProxyT< TParams >::GetWaitObject ( ) const
inline

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.

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

Returns
Returns the result event object of the stream grabber.
Thread Safety:
This method can be synchronized using an internal stream grabber lock.
Error Safety:
Does not throw C++ exceptions.
template<class TParams >
void Pylon::CNodeMapProxyT< TParams >::InvalidateNodes ( ) const
inlineinherited

Invalidates all nodes.

template<class TParams >
bool Pylon::CStreamGrabberProxyT< TParams >::IsOpen ( void  ) const
inline

Retrieve whether 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.
Returns
Returns true if the stream grabber is open.
Thread Safety:
This method can be synchronized using an internal stream grabber lock.
Error Safety:
Does not throw C++ exceptions.
template<class TParams >
bool Pylon::CStreamGrabberProxyT< TParams >::IsStartAndStopStreamingMandatory ( )
inline

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.
template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::Open ( )
inline

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.
template<class TParams >
void Pylon::CNodeMapProxyT< TParams >::Poll ( int64_t  ElapsedTime)
inlineinherited

Fires nodes which have a polling time.

template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::PrepareGrab ( )
inline

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.

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.

Note
There can be limitations depending on the transport layer technology used when using a large amount of buffers.

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.

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.
template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::QueueBuffer ( StreamBufferHandle  hStreamBuffer,
const void *  pContext = NULL 
)
inline

Enqueues a buffer in the input 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.
Parameters
[in]hStreamBufferThe handle of a buffer that has been provided by RegisterBuffer().
[in]pContextA user-provided pointer passed along with buffer in the internal input and output queues.
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.
template<class TParams >
StreamBufferHandle Pylon::CStreamGrabberProxyT< TParams >::RegisterBuffer ( void *  pBuffer,
size_t  bufferSize 
)
inline

Registers a buffer for subsequent use.

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.
Parameters
[in]pBufferThe pointer of the buffer that is to be used for grabbing e.g., for grabbing images.
[in]bufferSizeThe size of the provided buffer in bytes.
Returns
Returns a handle for the registered buffer that can be used in subsequent calls.
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.
template<class TParams >
bool Pylon::CStreamGrabberProxyT< TParams >::RetrieveResult ( GrabResult Result)
inline

Retrieves one grab result from 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.

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

Returns
Returns true when result was available.
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.
template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::StartStreamingIfMandatory ( )
inline

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.

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.

Note
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.
template<class TParams >
void Pylon::CStreamGrabberProxyT< TParams >::StopStreamingIfMandatory ( )
inline

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.

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.

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.

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

pylon 6.1.0
Copyright (c) 2006-2020 Basler AG (Mon Mar 16 2020 10:57:00)