Pylon Logo Basler Logo
Public Member Functions | Protected Member Functions | List of all members
Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT > Class Template Reference

Implementation Detail: Header only implementation class for creating device specific Instant Camera classes. More...

#include <pylon/private/DeviceSpecificInstantCamera.h>

Inheritance diagram for Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >:
Inheritance graph
[legend]

Public Member Functions

 CDeviceSpecificInstantCameraT ()
 Creates an Instant Camera object with no attached Pylon device. More...
 
 CDeviceSpecificInstantCameraT (IPylonDevice *pDevice, ECleanup cleanupProcedure=Cleanup_Delete)
 Creates an Instant Camera object and calls Attach(). More...
 
virtual ~CDeviceSpecificInstantCameraT ()
 Destroys an Instant Camera object. More...
 
virtual void Attach (IPylonDevice *pDevice, ECleanup cleanupProcedure=Cleanup_Delete)
 Attaches a Pylon device to the Instant Camera. More...
 
virtual void DestroyDevice ()
 Destroys the attached Pylon device. More...
 
virtual IPylonDeviceDetachDevice ()
 Detaches an attached Pylon device. More...
 
virtual void Open ()
 Opens the attached Pylon device. More...
 
virtual void Close ()
 Closes the attached Pylon device. More...
 
virtual bool RetrieveResult (unsigned int timeoutMs, typename CameraTraitsT::GrabResultPtr_t &grabResult, ETimeoutHandling timeoutHandling=TimeoutHandling_ThrowException)
 Retrieves a grab result according to the strategy, waits if it is not yet available. More...
 
virtual bool GrabOne (unsigned int timeoutMs, typename CameraTraitsT::GrabResultPtr_t &grabResult, ETimeoutHandling timeoutHandling=TimeoutHandling_ThrowException)
 Grabs one image. More...
 
virtual void RegisterConfiguration (typename CameraTraitsT::ConfigurationEventHandler_t *pConfigurator, ERegistrationMode mode, ECleanup cleanupProcedure)
 Adds a configurator to the list of registered configurator objects. More...
 
virtual bool DeregisterConfiguration (typename CameraTraitsT::ConfigurationEventHandler_t *configurator)
 Removes a configurator from the list of registered configurator objects. More...
 
virtual void RegisterImageEventHandler (typename CameraTraitsT::ImageEventHandler_t *pImageEventHandler, ERegistrationMode mode, ECleanup cleanupProcedure)
 Adds an image event handler to the list of registered image event handler objects. More...
 
virtual bool DeregisterImageEventHandler (typename CameraTraitsT::ImageEventHandler_t *imageEventHandler)
 Removes an image event handler from the list of registered image event handler objects. More...
 
virtual void RegisterCameraEventHandler (typename CameraTraitsT::CameraEventHandler_t *pCameraEventHandler, const String_t &nodeName, intptr_t userProvidedId, ERegistrationMode mode, ECleanup cleanupProcedure, ECameraEventAvailability availability=CameraEventAvailability_Mandatory)
 Adds an camera event handler to the list of registered camera event handler objects. More...
 
virtual bool DeregisterCameraEventHandler (typename CameraTraitsT::CameraEventHandler_t *cameraEventHandler, const String_t &nodeName)
 Removes a camera event handler from the list of registered camera event handler objects. More...
 
virtual const CameraTraitsT::DeviceInfo_t & GetDeviceInfo () const
 Provides access to the device info object of the attached Pylon device or an empty one. More...
 
virtual CameraTraitsT::TlParams_t & GetTLParams ()
 Provides access to the transport layer parameters of the attached Pylon Device. More...
 
virtual CameraTraitsT::StreamGrabberParams_t & GetStreamGrabberParams ()
 Provides access to the stream grabber parameters of the attached Pylon Device. More...
 
virtual CameraTraitsT::EventGrabberParams_t & GetEventGrabberParams ()
 Provides access to the event grabber parameters of the attached Pylon Device. More...
 
virtual bool IsPylonDeviceAttached () const
 Returns the Pylon device attached state of the Instant Camera object. More...
 
virtual bool IsCameraDeviceRemoved () const
 Returns the connection state of the camera device. More...
 
virtual bool HasOwnership () const
 Returns the ownership of the attached Pylon device. More...
 
virtual bool IsOpen () const
 Returns the open state of the attached Pylon device object. More...
 
virtual void StartGrabbing (EGrabStrategy strategy=GrabStrategy_OneByOne, EGrabLoop grabLoopType=GrabLoop_ProvidedByUser)
 Starts the grabbing of images. More...
 
virtual void StartGrabbing (size_t maxImages, EGrabStrategy strategy=GrabStrategy_OneByOne, EGrabLoop grabLoopType=GrabLoop_ProvidedByUser)
 Starts the grabbing for a maximum number of images. More...
 
virtual bool RetrieveResult (unsigned int timeoutMs, CGrabResultPtr &grabResult, ETimeoutHandling timeoutHandling=TimeoutHandling_ThrowException)
 Retrieves a grab result according to the strategy, waits if it is not yet available. More...
 
virtual void StopGrabbing ()
 Stops the grabbing of images. More...
 
virtual bool IsGrabbing () const
 Returns state of grabbing. More...
 
virtual bool GrabOne (unsigned int timeoutMs, CGrabResultPtr &grabResult, ETimeoutHandling timeoutHandling=TimeoutHandling_ThrowException)
 Grabs one image. More...
 
virtual size_t GetQueuedBufferCount ()
 Deprecated: This method has been deprecated. More...
 
virtual const WaitObjectGetGrabResultWaitObject ()
 Provides access to a wait object indicating available grab results. More...
 
virtual const WaitObjectGetGrabStopWaitObject ()
 Provides access to a wait object indicating that the grabbing has stopped. More...
 
virtual const WaitObjectGetCameraEventWaitObject ()
 Provides access to a wait object indicating available camera events. More...
 
virtual void RegisterConfiguration (CConfigurationEventHandler *pConfigurator, ERegistrationMode mode, ECleanup cleanupProcedure)
 Adds a configurator to the list of registered configurator objects. More...
 
virtual bool DeregisterConfiguration (CConfigurationEventHandler *configurator)
 Removes a configurator from the list of registered configurator objects. More...
 
virtual void RegisterImageEventHandler (CImageEventHandler *pImageEventHandler, ERegistrationMode mode, ECleanup cleanupProcedure)
 Adds an image event handler to the list of registered image event handler objects. More...
 
virtual bool DeregisterImageEventHandler (CImageEventHandler *imageEventHandler)
 Removes an image event handler from the list of registered image event handler objects. More...
 
virtual void RegisterCameraEventHandler (CCameraEventHandler *pCameraEventHandler, const String_t &nodeName, intptr_t userProvidedId, ERegistrationMode mode, ECleanup cleanupProcedure, ECameraEventAvailability availability=CameraEventAvailability_Mandatory)
 Adds an camera event handler to the list of registered camera event handler objects. More...
 
virtual bool DeregisterCameraEventHandler (CCameraEventHandler *cameraEventHandler, const String_t &nodeName)
 Removes a camera event handler from the list of registered camera event handler objects. More...
 
virtual bool WaitForFrameTriggerReady (unsigned int timeoutMs, ETimeoutHandling timeoutHandling=TimeoutHandling_ThrowException)
 Actively waits until the the camera is ready to accept a frame trigger. More...
 
virtual bool CanWaitForFrameTriggerReady () const
 Checks to see whether the camera device can be queried whether it is ready to accept the next frame trigger. More...
 
virtual void ExecuteSoftwareTrigger ()
 Executes the software trigger command. More...
 
virtual void SetCameraContext (intptr_t context)
 Sets a context that is attached to each grab result of the camera object on RetrieveResult(). More...
 
virtual intptr_t GetCameraContext () const
 Returns the context that is attached to each grab result of the camera object. More...
 
virtual GenApi::INodeMapGetNodeMap ()
 Provides access to the node map of the camera device. More...
 
virtual GenApi::INodeMapGetTLNodeMap ()
 Provides access to the transport layer node map of the attached Pylon device. More...
 
virtual GenApi::INodeMapGetStreamGrabberNodeMap ()
 Provides access to the stream grabber node map of the attached Pylon device. More...
 
virtual GenApi::INodeMapGetEventGrabberNodeMap ()
 Provides access to the event grabber node map of the attached Pylon device. More...
 
virtual GenApi::INodeMapGetInstantCameraNodeMap ()
 Provides access to the node map of the Instant Camera object. More...
 
virtual void SetBufferFactory (IBufferFactory *pFactory, ECleanup cleanupProcedure=Cleanup_Delete)
 Sets an alternative buffer factory that is used for buffer allocation. More...
 
virtual bool Is1394 () const
 Returns true if an IEEE 1394 Pylon device is attached to the Instant Camera object. More...
 
virtual bool IsGigE () const
 Returns true if a GigE Pylon device is attached to the Instant Camera object. More...
 
virtual bool IsUsb () const
 Returns true if a USB Pylon device is attached to the Instant Camera object. More...
 
virtual bool IsCameraLink () const
 Returns true if a Camera Link Pylon device is attached to the Instant Camera object. More...
 
virtual bool IsCxp () const
 Returns true if a CoaXPress GenTL device is attached to the Instant Camera object. More...
 
VersionInfo GetSfncVersion () const
 Returns the SFNC version read from the camera node map. More...
 
virtual bool IsBcon () const
 Returns true if a BCON Pylon device is attached to the Instant Camera object. More...
 

Public Attributes

Categories: Root
Pylon::IBooleanExAcquisitionStartStopExecutionEnable
 If set, this will automatically execute AcquisitionStart when calling StartGrabbing and AcquisitionStop when calling StopGrabbing This option is enabled by default - Applies to: InstantCamera. More...
 
Pylon::IBooleanExChunkNodeMapsEnable
 Enables/disables the use of a chunk node map for each grab result Grab result chunk node maps can be disabled to save resources - Applies to: InstantCamera. More...
 
Pylon::IBooleanExClearBufferModeEnable
 If set, all buffers will be cleared (set to 0) before grabbing an image Note that this requires additional processing time per frame - Applies to: InstantCamera. More...
 
Pylon::IBooleanExGrabCameraEvents
 Enables/disables the grabbing of camera events while images are grabbed Is writable when the camera object is closed - Applies to: InstantCamera. More...
 
Pylon::IIntegerExMaxNumBuffer
 The maximum number of buffers that are allocated and used for grabbing - Applies to: InstantCamera. More...
 
Pylon::IIntegerExMaxNumGrabResults
 The maximum number of grab results available at any time during a grab session This value can be limited to save resources Furthermore, it can be used to check that the grab results are returned correctly - Applies to: InstantCamera. More...
 
Pylon::IIntegerExMaxNumQueuedBuffer
 The maximum number of buffers that are queued in the stream grabber input queue - Applies to: InstantCamera. More...
 
Pylon::IBooleanExMigrationModeActive
 The migration mode is set up according to this setting at defined points e g , when the camera is opened - Applies to: InstantCamera. More...
 
Pylon::IBooleanExMonitorModeActive
 The camera object is set to monitor mode when enabled, e g when using the GigE multicast feature Is writable when the camera object is closed - Applies to: InstantCamera. More...
 
Pylon::IIntegerExNumEmptyBuffers
 The number of empty buffers that are not used for grabbing yet - Applies to: InstantCamera. More...
 
Pylon::IIntegerExNumQueuedBuffers
 The number of buffers queued at Low Level API stream grabber - Applies to: InstantCamera. More...
 
Pylon::IIntegerExNumReadyBuffers
 The number of grab result buffers in the output queue that are ready for retrieval - Applies to: InstantCamera. More...
 
Pylon::IIntegerExOutputQueueSize
 The size of the grab result buffer output queue - Applies to: InstantCamera. More...
 
Pylon::IIntegerExStaticChunkNodeMapPoolSize
 If larger than 0, a static chunk node map pool is used instead of dynamic chunk node map creation - Applies to: InstantCamera. More...
 
Categories: GrabLoopThread
Pylon::IIntegerExGrabLoopThreadPriority
 The grab loop thread priority - Applies to: InstantCamera. More...
 
Pylon::IBooleanExGrabLoopThreadPriorityOverride
 If enabled, the user can set a custom priority for the grab loop thread Otherwise, the priority of the newly created thread is not changed - Applies to: InstantCamera. More...
 
Pylon::IIntegerExGrabLoopThreadTimeout
 A custom timeout for the grab loop thread's call to RetrieveResult RetrieveResult is configured to throw an exception on timeout, which will stop the grab session - Applies to: InstantCamera. More...
 
Pylon::IBooleanExGrabLoopThreadUseTimeout
 If enabled, the user can set a custom timeout for the grab loop thread's call to RetrieveResult RetrieveResult is configured to throw an exception on timeout, which will stop the grab session - Applies to: InstantCamera. More...
 
Categories: InternalGrabEngineThread
Pylon::IIntegerExInternalGrabEngineThreadPriority
 The internal grab engine thread priority - Applies to: InstantCamera. More...
 
Pylon::IBooleanExInternalGrabEngineThreadPriorityOverride
 If enabled, the user can set a custom priority for the internal grab engine thread operating the stream grabber Otherwise the priority defaults to 25 - Applies to: InstantCamera. More...
 

Protected Member Functions

virtual IPylonDeviceGetDevice ()
 Provides access to the attached Pylon device. More...
 
CLockGetLock ()
 Provides access to the lock used for synchronizing the access to the camera. More...
 

Detailed Description

template<typename CameraTraitsT>
class Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >

Implementation Detail: Header only implementation class for creating device specific Instant Camera classes.

Constructor & Destructor Documentation

template<typename CameraTraitsT >
Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::CDeviceSpecificInstantCameraT ( )

Creates an Instant Camera object with no attached Pylon device.

Error Safety:
Does not throw C++ exceptions.
template<typename CameraTraitsT >
Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::CDeviceSpecificInstantCameraT ( IPylonDevice pDevice,
ECleanup  cleanupProcedure = Cleanup_Delete 
)

Creates an Instant Camera object and calls Attach().

See Attach() for more information.

Parameters
[in]pDeviceThe Pylon device to attach.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the Pylon device is destroyed when the Instant Camera object is destroyed.
Error Safety:
May throw an exception if the passed Pylon device is open. Does not throw C++ exceptions if the passed Pylon device is closed or NULL.
template<typename CameraTraitsT >
Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::~CDeviceSpecificInstantCameraT ( )
virtual

Destroys an Instant Camera object.

Calls Attach( NULL) for destroying or removing a Pylon device depending on the passed cleanup procedure.

Error Safety:
Does not throw C++ exceptions.

Member Function Documentation

template<typename CameraTraitsT >
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::Attach ( IPylonDevice pDevice,
ECleanup  cleanupProcedure = Cleanup_Delete 
)
virtual

Attaches a Pylon device to the Instant Camera.

Parameters
[in]pDeviceThe Pylon device to attach.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the Pylon device is destroyed when the Instant Camera object is destroyed.
  • If a Pylon device is currently attached, it is destroyed (DestroyDevice()) or removed (DetachDevice()) depending on the previously set cleanup procedure value.
  • If the pDevice parameter is NULL, nothing more is done.
  • The OnAttach configuration event is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
  • The new Pylon device is attached.
  • The instant camera migration mode setting is applied to the Pylon device transport layer node map.
  • If the passed Pylon device is open, callbacks for camera events are registered at the camera node map. (This may fail)
  • If the passed Pylon device is open, a device removal call back is registered. (This may fail)
  • If the passed Pylon device is open, access modifiers (see IPylonDevice::Open()) are carried over as camera parameters.
  • The OnAttached configuration event is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
Postcondition
  • If the passed pointer to the Pylon device is NULL, the Instant Camera object is in the "no device attached" state.
  • If the passed pointer to the Pylon device is not NULL, the passed Pylon device is attached.
  • If the set cleanup procedure equals Cleanup_Delete, the Pylon device is destroyed when the Instant Camera object is destroyed or a new device is attached.
  • If the passed Pylon device is open and the registration of callbacks fails, the Instant Camera object is in the "no device attached" state.
  • The opened-by-user flag is set, preventing closing of the Pylon device on StopGrabbing() when the attached Pylon device is already open.
Error Safety:
May throw an exception if the passed Pylon device is open. Does not throw C++ exceptions if the passed Pylon device is closed or NULL.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Reimplemented from Pylon::CInstantCamera.

virtual bool Pylon::CInstantCamera::CanWaitForFrameTriggerReady ( ) const
virtualinherited

Checks to see whether the camera device can be queried whether it is ready to accept the next frame trigger.

If 'FrameTriggerWait' can be selected for 'AcquisitionStatusSelector' and 'AcquisitionStatus' is readable, the camera device can be queried whether it is ready to accept the next frame trigger.

If the nodes mentioned above are not available and the 'SoftwareTrigger' node is readable, the camera device can be queried whether it is ready to accept the next frame trigger.

Note
If a camera device can't be queried whether it is ready to accept the next frame trigger, the camera device is ready to accept the next trigger after the last image triggered has been grabbed, e.g. after you have retrieved the last image triggered using RetrieveResult(). Camera devices that can be queried whether they are ready to accept the next frame trigger, may not be ready for the next frame trigger after the last image triggered has been grabbed.
Returns
Returns true if the camera is open and the camera device can be queried whether it is ready to accept the next frame trigger.
Postcondition
The 'AcquisitionStatusSelector' is set to 'FrameTriggerWait' if writable.
Error Safety:
Accessing the camera registers may fail.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT >
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::Close ( )
virtual

Closes the attached Pylon device.

  • If no Pylon device is attached, nothing is done.
  • If the Pylon device is already closed, nothing is done.
  • If a grab is in progress, it is stopped by calling StopGrabbing().
  • The configuration event OnClose is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
  • The connection to the camera device is closed and the Pylon device is closed.
  • The configuration event OnClosed is fired if the Pylon device has been closed successfully. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
Postcondition
The connection to the camera device is closed and the Pylon device is closed.
Error Safety:
Does not throw C++ exceptions. Possible C++ exceptions are caught and ignored.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Reimplemented from Pylon::CInstantCamera.

template<typename CameraTraitsT>
bool Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::DeregisterCameraEventHandler ( typename CameraTraitsT::CameraEventHandler_t *  cameraEventHandler,
const String_t nodeName 
)
virtual

Removes a camera event handler from the list of registered camera event handler objects.

If the camera event handler is not found, nothing is done.

Parameters
[in]cameraEventHandlerThe registered receiver of camera events.
[in]nodeNameThe name of the event data node updated on camera event, e.g. "ExposureEndEventTimestamp" for exposure end event.
Returns
True if successful
Postcondition
  • The cameraEventHandler is deregistered.
  • If the camera event handler has been registered by passing a pointer and the cleanup procedure is Cleanup_Delete, the event handler is deleted.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the camera event handler lock. If the camera is open, the camera node map lock is also used for synchronization.
virtual bool Pylon::CInstantCamera::DeregisterCameraEventHandler ( CCameraEventHandler cameraEventHandler,
const String_t nodeName 
)
virtualinherited

Removes a camera event handler from the list of registered camera event handler objects.

If the camera event handler is not found, nothing is done.

Parameters
[in]cameraEventHandlerThe registered receiver of camera events.
[in]nodeNameThe name of the event data node updated on camera event, e.g. "ExposureEndEventTimestamp" for exposure end event.
Returns
True if successful
Postcondition
  • The cameraEventHandler is deregistered.
  • If the camera event handler has been registered by passing a pointer and the cleanup procedure is Cleanup_Delete, the event handler is deleted.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the camera event handler lock. If the camera is open, the camera node map lock is also used for synchronization.
template<typename CameraTraitsT>
bool Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::DeregisterConfiguration ( typename CameraTraitsT::ConfigurationEventHandler_t *  configurator)
virtual

Removes a configurator from the list of registered configurator objects.

If the configurator is not found, nothing is done.

Parameters
[in]configuratorThe registered receiver of configuration events.
Returns
True if successful
Postcondition
  • The configurator is deregistered.
  • If the configuration has been registered by passing a pointer and the cleanup procedure is Cleanup_Delete, the event handler is deleted.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::DeregisterConfiguration ( CConfigurationEventHandler configurator)
virtualinherited

Removes a configurator from the list of registered configurator objects.

If the configurator is not found, nothing is done.

Parameters
[in]configuratorThe registered receiver of configuration events.
Returns
True if successful
Postcondition
  • The configurator is deregistered.
  • If the configuration has been registered by passing a pointer and the cleanup procedure is Cleanup_Delete, the event handler is deleted.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT>
bool Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::DeregisterImageEventHandler ( typename CameraTraitsT::ImageEventHandler_t *  imageEventHandler)
virtual

Removes an image event handler from the list of registered image event handler objects.

If the image event handler is not found, nothing is done.

Parameters
[in]imageEventHandlerThe registered receiver of configuration events.
Returns
True if successful
Postcondition
  • The imageEventHandler is deregistered.
  • If the image event handler has been registered by passing a pointer and the cleanup procedure is Cleanup_Delete, the event handler is deleted.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the internal image event handler registry lock.
virtual bool Pylon::CInstantCamera::DeregisterImageEventHandler ( CImageEventHandler imageEventHandler)
virtualinherited

Removes an image event handler from the list of registered image event handler objects.

If the image event handler is not found, nothing is done.

Parameters
[in]imageEventHandlerThe registered receiver of configuration events.
Returns
True if successful
Postcondition
  • The imageEventHandler is deregistered.
  • If the image event handler has been registered by passing a pointer and the cleanup procedure is Cleanup_Delete, the event handler is deleted.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the internal image event handler registry lock.
template<typename CameraTraitsT >
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::DestroyDevice ( )
virtual

Destroys the attached Pylon device.

Attention
The node maps, e.g. the camera node map, of the attached Pylon device must not be accessed anymore while destroying the Pylon device.
  • If no Pylon device is attached, nothing is done.
  • If the Pylon device is open, it is closed by calling Close().
  • The configuration event OnDestroy is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
  • The Pylon device is destroyed even if the cleanup procedure Cleanup_None has been passed when calling Attach() before.
  • The configuration event OnDestroyed is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
Postcondition
No Pylon device is attached.
Error Safety:
Does not throw C++ exceptions. Possible C++ exceptions are caught and ignored.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Reimplemented from Pylon::CInstantCamera.

template<typename CameraTraitsT >
IPylonDevice * Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::DetachDevice ( )
virtual

Detaches an attached Pylon device.

  • If no Pylon device is attached, nothing is done.
  • If a grab is in progress, it is stopped by calling StopGrabbing().
  • The configuration event OnDetach is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
  • The Pylon device is detached.
  • The configuration event OnDetached is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
Returns
The attached Pylon device or NULL if nothing has been attached before.
Postcondition
  • No Pylon device is attached.
  • The ownership of the Pylon device goes to the caller who is responsible for destroying the Pylon device.
Error Safety:
Does not throw C++ exceptions. Possible C++ exceptions are caught and ignored.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Reimplemented from Pylon::CInstantCamera.

virtual void Pylon::CInstantCamera::ExecuteSoftwareTrigger ( )
virtualinherited

Executes the software trigger command.

The camera needs to be configured for software trigger mode. Additionally, the camera needs to be ready to accept triggers. When triggering a frame this can be checked using the WaitForFrameTriggerReady() method;

Note
The application has to make sure that the correct trigger is selected before calling ExecuteSoftwareTrigger(). This can be done via the camera's TriggerSelector node. The Pylon::CSoftwareTriggerConfiguration selects the correct trigger when the Instant Camera is opened.
Precondition
  • The grabbing is started.
  • The camera device supports software trigger.
  • The software trigger is available. This depends on the configuration of the camera device.
Error Safety:
Accessing the camera registers may fail. Throws an exception on timeout if timeoutHandling is TimeoutHandling_ThrowException.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual intptr_t Pylon::CInstantCamera::GetCameraContext ( ) const
virtualinherited

Returns the context that is attached to each grab result of the camera object.

Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual const WaitObject& Pylon::CInstantCamera::GetCameraEventWaitObject ( )
virtualinherited

Provides access to a wait object indicating available camera events.

This wait object is Pylon device specific and changes when a new Pylon device is attached to the camera.

Returns
A wait object indicating available camera events.
Precondition
  • A Pylon device is attached.
  • The Pylon device is open.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual IPylonDevice* Pylon::CInstantCamera::GetDevice ( )
protectedvirtualinherited

Provides access to the attached Pylon device.

Returns
Pointer to the attached Pylon device.
Precondition
A Pylon device is attached.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT >
const CameraTraitsT::DeviceInfo_t & Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::GetDeviceInfo ( ) const
virtual

Provides access to the device info object of the attached Pylon device or an empty one.

Returns
The info object of the attached Pylon device or an empty one.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Reimplemented from Pylon::CInstantCamera.

virtual GenApi::INodeMap& Pylon::CInstantCamera::GetEventGrabberNodeMap ( )
virtualinherited

Provides access to the event grabber node map of the attached Pylon device.

Returns
Reference to the event grabber node map of the attached Pylon device or a reference to the empty node map if event grabbing is not supported. The GENAPI_NAMESPACE::INodeMap::GetNumNodes() method can be used to check whether the node map is empty.
Precondition
  • A Pylon device is attached.
  • The Pylon device is open.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT >
CameraTraitsT::EventGrabberParams_t & Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::GetEventGrabberParams ( )
virtual

Provides access to the event grabber parameters of the attached Pylon Device.

Returns
Reference to the event grabber parameters.
Precondition
  • A Pylon Device is attached.
  • The Pylon Device is open.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual const WaitObject& Pylon::CInstantCamera::GetGrabResultWaitObject ( )
virtualinherited

Provides access to a wait object indicating available grab results.

Returns
A wait object indicating available grab results.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual const WaitObject& Pylon::CInstantCamera::GetGrabStopWaitObject ( )
virtualinherited

Provides access to a wait object indicating that the grabbing has stopped.

Returns
A wait object indicating that the grabbing has stopped.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual GenApi::INodeMap& Pylon::CInstantCamera::GetInstantCameraNodeMap ( )
virtualinherited

Provides access to the node map of the Instant Camera object.

The node map of the camera device is made available by the GetNodeMap() method.

Returns
Reference to the node map of the Instant Camera object.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
CLock& Pylon::CInstantCamera::GetLock ( )
protectedinherited

Provides access to the lock used for synchronizing the access to the camera.

This lock can be used when extending the Instant Camera class.

Example:

class CMyInstantCamera : public CInstantCamera
{
// Method extending the Instant Camera class
void Foo()
{
// Scoped Lock.
AutoLock lock( CInstantCamera::GetLock());
//...
}
};
Error Safety:
Does not throw C++ exceptions.
virtual GenApi::INodeMap& Pylon::CInstantCamera::GetNodeMap ( )
virtualinherited

Provides access to the node map of the camera device.

The Pylon device must be opened before reading ore writing any parameters of the camera device. This can be done using the Open() method of the Instant Camera class.

Returns
Reference to the node map of the camera device.
Precondition
A Pylon device is attached.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual size_t Pylon::CInstantCamera::GetQueuedBufferCount ( )
virtualinherited

Deprecated: This method has been deprecated.

Use the NumQueuedBuffers parameter instead.

Returns
The number of buffers that are queued for grabbing.
VersionInfo Pylon::CInstantCamera::GetSfncVersion ( ) const
inherited

Returns the SFNC version read from the camera node map.

The SFNC version is read from the camera node map using the integer nodes DeviceSFNCVersionMajor, DeviceSFNCVersionMinor, and DeviceSFNCVersionSubMinor.

Returns
The SFNC version used by the camera device. The returned SFNC version is 0.0.0 (Pylon::Sfnc_VersionUndefined) if no SFNC version information is provided by the camera device.
Precondition
A Pylon device is attached.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual GenApi::INodeMap& Pylon::CInstantCamera::GetStreamGrabberNodeMap ( )
virtualinherited

Provides access to the stream grabber node map of the attached Pylon device.

Returns
Reference to the stream grabber node map of the attached Pylon device or the reference to the empty node map if grabbing is not supported. The GENAPI_NAMESPACE::INodeMap::GetNumNodes() method can be used to check whether the node map is empty.
Precondition
  • A Pylon device is attached.
  • The Pylon device is open.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT >
CameraTraitsT::StreamGrabberParams_t & Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::GetStreamGrabberParams ( )
virtual

Provides access to the stream grabber parameters of the attached Pylon Device.

Returns
Reference to the stream grabber parameters.
Precondition
  • A Pylon Device is attached.
  • The Pylon Device is open.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual GenApi::INodeMap& Pylon::CInstantCamera::GetTLNodeMap ( )
virtualinherited

Provides access to the transport layer node map of the attached Pylon device.

Returns
Reference to the transport layer node map of the attached Pylon device or the reference to the empty node map if a transport layer node map is not supported. The GENAPI_NAMESPACE::INodeMap::GetNumNodes() method can be used to check whether the node map is empty.
Precondition
A Pylon device is attached.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT >
CameraTraitsT::TlParams_t & Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::GetTLParams ( )
virtual

Provides access to the transport layer parameters of the attached Pylon Device.

Returns
Reference to the transport layer parameters.
Precondition
A Pylon Device is attached.
Error Safety:
The Instant Camera object is still valid after error.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT>
bool Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::GrabOne ( unsigned int  timeoutMs,
typename CameraTraitsT::GrabResultPtr_t &  grabResult,
ETimeoutHandling  timeoutHandling = TimeoutHandling_ThrowException 
)
virtual

Grabs one image.

The following code shows a simplified version of what is done (happy path):

//grab one image
//grab is stopped automatically due to maxImages = 1
return RetrieveResult( timeoutMs, grabResult, timeoutHandling) && grabResult->GrabSucceeded();

GrabOne() can be used to together with the CAcquireSingleFrameConfiguration.

Note
Using GrabOne is more efficient if the Pylon device is already open, otherwise the Pylon device is opened and closed for each call.
Grabbing single images using Software Trigger (CSoftwareTriggerConfiguration) is recommended if you want to maximize frame rate. This is because the overhead per grabbed image is reduced compared to Single Frame Acquisition. The grabbing can be started using StartGrabbing(). Images are grabbed using the WaitForFrameTriggerReady(), ExecuteSoftwareTrigger() and RetrieveResult() methods instead of using GrabOne. The grab can be stopped using StopGrabbing() when done.
Parameters
[in]timeoutMsA timeout value in ms for waiting for a grab result, or the INFINITE value.
[out]grabResultReceives the grab result.
[in]timeoutHandlingIf timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout.
Returns
Returns true if the call successfully retrieved a grab result and the grab succeeded (CGrabResultData::GrabSucceeded()).
Precondition
Must meet the preconditions of start grabbing.
Postcondition
Meets the postconditions of stop grabbing.
Error Safety:
The Instant Camera object is still valid after error. See StartGrabbing(), RetrieveResult(), and StopGrabbing() . In the case of exceptions after StartGrabbing() the grabbing is stopped using StopGrabbing().
virtual bool Pylon::CInstantCamera::GrabOne ( unsigned int  timeoutMs,
CGrabResultPtr grabResult,
ETimeoutHandling  timeoutHandling = TimeoutHandling_ThrowException 
)
virtualinherited

Grabs one image.

The following code shows a simplified version of what is done (happy path):

//grab one image
//grab is stopped automatically due to maxImages = 1
return RetrieveResult( timeoutMs, grabResult, timeoutHandling) && grabResult->GrabSucceeded();

GrabOne() can be used to together with the CAcquireSingleFrameConfiguration.

Note
Using GrabOne is more efficient if the Pylon device is already open, otherwise the Pylon device is opened and closed for each call.
Grabbing single images using Software Trigger (CSoftwareTriggerConfiguration) is recommended if you want to maximize frame rate. This is because the overhead per grabbed image is reduced compared to Single Frame Acquisition. The grabbing can be started using StartGrabbing(). Images are grabbed using the WaitForFrameTriggerReady(), ExecuteSoftwareTrigger() and RetrieveResult() methods instead of using GrabOne. The grab can be stopped using StopGrabbing() when done.
Parameters
[in]timeoutMsA timeout value in ms for waiting for a grab result, or the INFINITE value.
[out]grabResultReceives the grab result.
[in]timeoutHandlingIf timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout.
Returns
Returns true if the call successfully retrieved a grab result and the grab succeeded (CGrabResultData::GrabSucceeded()).
Precondition
Must meet the preconditions of start grabbing.
Postcondition
Meets the postconditions of stop grabbing.
Error Safety:
The Instant Camera object is still valid after error. See StartGrabbing(), RetrieveResult(), and StopGrabbing() . In the case of exceptions after StartGrabbing() the grabbing is stopped using StopGrabbing().
virtual bool Pylon::CInstantCamera::HasOwnership ( ) const
virtualinherited

Returns the ownership of the attached Pylon device.

Returns
True if a Pylon device is attached and the Instant Camera object has been given the ownership by passing the cleanup procedure Cleanup_Delete when calling Attach().
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::Is1394 ( ) const
virtualinherited

Returns true if an IEEE 1394 Pylon device is attached to the Instant Camera object.

This method is provided for convenience only. The device type can also be determined as shown in the following example.

...
if (camera.GetDeviceInfo().GetDeviceClass() == Basler1394DeviceClass)
{
...
}
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsBcon ( ) const
virtualinherited

Returns true if a BCON Pylon device is attached to the Instant Camera object.

This method is provided for convenience only. The device type can also be determined as shown in the following example.

...
if (camera.GetDeviceInfo().GetDeviceClass() == BaslerBconDeviceClass)
{
...
}
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsCameraDeviceRemoved ( ) const
virtualinherited

Returns the connection state of the camera device.

Attention
Due to technical reasons, the IsCameraDeviceRemoved() property may not be updated immediately after the first error caused by a device removal occurs.

The device removal is only detected while the Instant Camera and therefore the attached Pylon device are open.

The attached Pylon device is not operable anymore if the camera device has been removed from the PC. After it is made sure that no access to the Pylon device or any of its node maps is made anymore the Pylon device should be destroyed using CInstantCamera::DeviceDestroy(). The access to the Pylon device can be protected using the lock provided by GetLock(), e.g. when accessing parameters.

Returns
True if the camera device removal from the PC has been detected.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsCameraLink ( ) const
virtualinherited

Returns true if a Camera Link Pylon device is attached to the Instant Camera object.

This method is provided for convenience only. The device type can also be determined as shown in the following example.

...
if (camera.GetDeviceInfo().GetDeviceClass() == BaslerCameraLinkDeviceClass)
{
...
}
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsCxp ( ) const
virtualinherited

Returns true if a CoaXPress GenTL device is attached to the Instant Camera object.

This method is provided for convenience only.

Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsGigE ( ) const
virtualinherited

Returns true if a GigE Pylon device is attached to the Instant Camera object.

This method is provided for convenience only. The device type can also be determined as shown in the following example.

...
if (camera.GetDeviceInfo().GetDeviceClass() == BaslerGigEDeviceClass)
{
...
}
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsGrabbing ( ) const
virtualinherited

Returns state of grabbing.

The camera object is grabbing after a successful call to StartGrabbing() until StopGrabbing() is called.

Returns
Returns true if still grabbing.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsOpen ( ) const
virtualinherited

Returns the open state of the attached Pylon device object.

Note
This method still returns true if the camera device has been physically removed from the PC while the attached Pylon device object is open. The Pylon device object will not automatically close itself on device removal. It must be closed by calling CInstantCamera::Close(). The IsCameraDeviceRemoved() method can be used to check if the connection to the camera device has been lost while the attached Pylon device object is open.
Error Safety: Does not throw C++ exceptions.
Returns
Returns true if a Pylon device is attached and it is open.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsPylonDeviceAttached ( ) const
virtualinherited

Returns the Pylon device attached state of the Instant Camera object.

Returns
True if a Pylon device is attached.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::IsUsb ( ) const
virtualinherited

Returns true if a USB Pylon device is attached to the Instant Camera object.

This method is provided for convenience only. The device type can also be determined as shown in the following example.

...
if (camera.GetDeviceInfo().GetDeviceClass() == BaslerUsbDeviceClass)
{
...
}
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT >
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::Open ( )
virtual

Opens the attached Pylon device.

  • Opened by user flag is set, preventing closing of the device on StopGrabbing().
  • If the Pylon device is already open, nothing more is done.
  • The OnOpen configuration event is fired. The notification of event handlers stops when an event call triggers an exception.
  • The Pylon device is opened and a connection to the camera device is established.
  • The instant camera migration mode setting is applied to the Pylon device transport layer node map.
  • A device removal call back is registered at the Pylon device.
  • Callbacks for camera events are registered at the camera node map.
  • The OnOpened configuration event is fired if the Pylon device has been opened successfully. The notification of event handlers stops when an event call triggers an exception.
Precondition
A Pylon device is attached.
Postcondition
  • The Pylon device is open and a connection to the camera device has been established.
  • Opened by user flag is set, preventing closing of the Pylon device on StopGrabbing().
Error Safety:
The Instant Camera object is still valid after error. The Pylon device open may throw. Configuration event calls may throw. Callback registrations may throw. The Pylon device is closed with Close() if the OnOpened event call triggers an exception.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Reimplemented from Pylon::CInstantCamera.

template<typename CameraTraitsT>
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::RegisterCameraEventHandler ( typename CameraTraitsT::CameraEventHandler_t *  pCameraEventHandler,
const String_t nodeName,
intptr_t  userProvidedId,
ERegistrationMode  mode,
ECleanup  cleanupProcedure,
ECameraEventAvailability  availability = CameraEventAvailability_Mandatory 
)
virtual

Adds an camera event handler to the list of registered camera event handler objects.

  • If mode equals RegistrationMode_ReplaceAll, the list of registered camera event handlers is cleared.
  • If the pointer pCameraEventHandler is not NULL, it is appended to the list of camera event handlers.
Parameters
[in]pCameraEventHandlerThe receiver of camera events.
[in]nodeNameThe name of the event data node updated on camera event, e.g. "ExposureEndEventTimestamp" for exposure end event.
[in]userProvidedIdThis ID is passed as a parameter in CCameraEventHandler::OnCameraEvent and can be used to distinguish between different events. It is recommended to create an own application specific enum and use it's values as IDs.
[in]modeIndicates how to register the new cameraEventHandler.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed.
[in]availabilityIf availability equals CameraEventAvailability_Mandatory, the camera must support the data node specified by node name. If not, an exception is thrown when the Instant Camera is open, the Instant Camera is opened, or an open Pylon device is attached.

Internally, a GenApi node call back is registered for the node identified by nodeName. This callback triggers a call to the CCameraEventHandler::OnCameraEvent() method. That's why a Camera Event Handler can be registered for any node of the camera node map to get informed about changes.

Postcondition
The cameraEventHandler is registered and called on camera events.
Error Safety:
Throws an exception if the availability is set to CameraEventAvailability_Mandatory and the node with the name nodeName is not available in the camera node map (see GetNodeMap()). Throws an exception fail if the node callback registration fails. The event handler is not registered when an C++ exception is thrown.
Thread Safety:
This method is synchronized using the camera event handler lock. If the camera is open, the lock provided by GetLock() and the camera node map lock are also used for synchronization.
virtual void Pylon::CInstantCamera::RegisterCameraEventHandler ( CCameraEventHandler pCameraEventHandler,
const String_t nodeName,
intptr_t  userProvidedId,
ERegistrationMode  mode,
ECleanup  cleanupProcedure,
ECameraEventAvailability  availability = CameraEventAvailability_Mandatory 
)
virtualinherited

Adds an camera event handler to the list of registered camera event handler objects.

  • If mode equals RegistrationMode_ReplaceAll, the list of registered camera event handlers is cleared.
  • If the pointer pCameraEventHandler is not NULL, it is appended to the list of camera event handlers.
Parameters
[in]pCameraEventHandlerThe receiver of camera events.
[in]nodeNameThe name of the event data node updated on camera event, e.g. "ExposureEndEventTimestamp" for exposure end event.
[in]userProvidedIdThis ID is passed as a parameter in CCameraEventHandler::OnCameraEvent and can be used to distinguish between different events. It is recommended to create an own application specific enum and use it's values as IDs.
[in]modeIndicates how to register the new cameraEventHandler.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed.
[in]availabilityIf availability equals CameraEventAvailability_Mandatory, the camera must support the data node specified by node name. If not, an exception is thrown when the Instant Camera is open, the Instant Camera is opened, or an open Pylon device is attached.

Internally, a GenApi node call back is registered for the node identified by nodeName. This callback triggers a call to the CCameraEventHandler::OnCameraEvent() method. That's why a Camera Event Handler can be registered for any node of the camera node map to get informed about changes.

Postcondition
The cameraEventHandler is registered and called on camera events.
Error Safety:
Throws an exception if the availability is set to CameraEventAvailability_Mandatory and the node with the name nodeName is not available in the camera node map (see GetNodeMap()). Throws an exception fail if the node callback registration fails. The event handler is not registered when an C++ exception is thrown.
Thread Safety:
This method is synchronized using the camera event handler lock. If the camera is open, the lock provided by GetLock() and the camera node map lock are also used for synchronization.
template<typename CameraTraitsT>
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::RegisterConfiguration ( typename CameraTraitsT::ConfigurationEventHandler_t *  pConfigurator,
ERegistrationMode  mode,
ECleanup  cleanupProcedure 
)
virtual

Adds a configurator to the list of registered configurator objects.

  • If mode equals RegistrationMode_ReplaceAll, the list of registered configurators is cleared.
  • If pointer pConfigurator is not NULL, it is appended to the list of configurators.
Parameters
[in]pConfiguratorThe receiver of configuration events.
[in]modeIndicates how to register the new configurator.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed.
Postcondition
The configurator is registered and called on configuration events.
Error Safety:
Does not throw C++ exceptions, except when memory allocation fails.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual void Pylon::CInstantCamera::RegisterConfiguration ( CConfigurationEventHandler pConfigurator,
ERegistrationMode  mode,
ECleanup  cleanupProcedure 
)
virtualinherited

Adds a configurator to the list of registered configurator objects.

  • If mode equals RegistrationMode_ReplaceAll, the list of registered configurators is cleared.
  • If pointer pConfigurator is not NULL, it is appended to the list of configurators.
Parameters
[in]pConfiguratorThe receiver of configuration events.
[in]modeIndicates how to register the new configurator.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed.
Postcondition
The configurator is registered and called on configuration events.
Error Safety:
Does not throw C++ exceptions, except when memory allocation fails.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
template<typename CameraTraitsT>
void Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::RegisterImageEventHandler ( typename CameraTraitsT::ImageEventHandler_t *  pImageEventHandler,
ERegistrationMode  mode,
ECleanup  cleanupProcedure 
)
virtual

Adds an image event handler to the list of registered image event handler objects.

  • If mode equals RegistrationMode_ReplaceAll, the list of registered image event handlers is cleared.
  • If pointer pImageEventHandler is not NULL, it is appended to the list of image event handlers.
Parameters
[in]pImageEventHandlerThe receiver of image events.
[in]modeIndicates how to register the new imageEventHandler.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed.
Postcondition
The imageEventHandler is registered and called on image related events.
Error Safety:
Does not throw C++ exceptions, except when memory allocation fails.
Thread Safety:
This method is synchronized using the internal image event handler registry lock.
virtual void Pylon::CInstantCamera::RegisterImageEventHandler ( CImageEventHandler pImageEventHandler,
ERegistrationMode  mode,
ECleanup  cleanupProcedure 
)
virtualinherited

Adds an image event handler to the list of registered image event handler objects.

  • If mode equals RegistrationMode_ReplaceAll, the list of registered image event handlers is cleared.
  • If pointer pImageEventHandler is not NULL, it is appended to the list of image event handlers.
Parameters
[in]pImageEventHandlerThe receiver of image events.
[in]modeIndicates how to register the new imageEventHandler.
[in]cleanupProcedureIf cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed.
Postcondition
The imageEventHandler is registered and called on image related events.
Error Safety:
Does not throw C++ exceptions, except when memory allocation fails.
Thread Safety:
This method is synchronized using the internal image event handler registry lock.
template<typename CameraTraitsT>
bool Pylon::CDeviceSpecificInstantCameraT< CameraTraitsT >::RetrieveResult ( unsigned int  timeoutMs,
typename CameraTraitsT::GrabResultPtr_t &  grabResult,
ETimeoutHandling  timeoutHandling = TimeoutHandling_ThrowException 
)
virtual

Retrieves a grab result according to the strategy, waits if it is not yet available.

  • The content of the passed grab result is released.
  • If no Pylon device is attached or the grabbing is not started, the method returns immediately "false".
  • Wait for a grab result if it is not yet available. The access to the camera is not locked during waiting. Camera events are handled.
  • Only if camera events are used: Incoming camera events are handled.
  • One grab result is retrieved per call according to the strategy applied.
  • Only if chunk mode is used: The chunk data parsing is performed. The grab result data is updated using chunk data.
  • The image event OnImagesSkipped is fired if grab results have been skipped according to the strategy. The notification of event handlers stops when an event call triggers an exception.
  • The image event OnImageGrabbed is fired if a grab result becomes available. The notification of event handlers stops when an event call triggers an exception.
  • Stops the grabbing by calling StopGrabbing() if the maximum number of images has been grabbed.

It needs to be checked whether the grab represented by the grab result has been successful, see CGrabResultData::GrabSucceeded().

Parameters
[in]timeoutMsA timeout value in ms for waiting for a grab result, or the INFINITE value.
[out]grabResultReceives the grab result.
[in]timeoutHandlingIf timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout.
Returns
True if the call successfully retrieved a grab result, false otherwise.
Precondition
  • There is no other thread waiting for a result. This will be the case when the Instant Camera grab loop thread is used.
Postcondition
  • If a grab result has been retrieved, one image is removed from the output queue and is returned in the grabResult parameter.
  • If no grab result has been retrieved, an empty grab result is returned in the grabResult parameter.
  • If the maximum number of images has been grabbed, the grabbing is stopped.
  • If camera event handling is enabled and camera events were received, at least one or more camera event messages have been processed.
Error Safety:
The Instant Camera object is still valid after error. The grabbing is stopped if an exception is thrown.
Thread Safety:
This method is synchronized using the lock provided by GetLock() while not waiting.
virtual bool Pylon::CInstantCamera::RetrieveResult ( unsigned int  timeoutMs,
CGrabResultPtr grabResult,
ETimeoutHandling  timeoutHandling = TimeoutHandling_ThrowException 
)
virtualinherited

Retrieves a grab result according to the strategy, waits if it is not yet available.

  • The content of the passed grab result is released.
  • If no Pylon device is attached or the grabbing is not started, the method returns immediately "false".
  • Wait for a grab result if it is not yet available. The access to the camera is not locked during waiting. Camera events are handled.
  • Only if camera events are used: Incoming camera events are handled.
  • One grab result is retrieved per call according to the strategy applied.
  • Only if chunk mode is used: The chunk data parsing is performed. The grab result data is updated using chunk data.
  • The image event OnImagesSkipped is fired if grab results have been skipped according to the strategy. The notification of event handlers stops when an event call triggers an exception.
  • The image event OnImageGrabbed is fired if a grab result becomes available. The notification of event handlers stops when an event call triggers an exception.
  • Stops the grabbing by calling StopGrabbing() if the maximum number of images has been grabbed.

It needs to be checked whether the grab represented by the grab result has been successful, see CGrabResultData::GrabSucceeded().

Parameters
[in]timeoutMsA timeout value in ms for waiting for a grab result, or the INFINITE value.
[out]grabResultReceives the grab result.
[in]timeoutHandlingIf timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout.
Returns
True if the call successfully retrieved a grab result, false otherwise.
Precondition
  • There is no other thread waiting for a result. This will be the case when the Instant Camera grab loop thread is used.
Postcondition
  • If a grab result has been retrieved, one image is removed from the output queue and is returned in the grabResult parameter.
  • If no grab result has been retrieved, an empty grab result is returned in the grabResult parameter.
  • If the maximum number of images has been grabbed, the grabbing is stopped.
  • If camera event handling is enabled and camera events were received, at least one or more camera event messages have been processed.
Error Safety:
The Instant Camera object is still valid after error. The grabbing is stopped if an exception is thrown.
Thread Safety:
This method is synchronized using the lock provided by GetLock() while not waiting.
virtual void Pylon::CInstantCamera::SetBufferFactory ( IBufferFactory pFactory,
ECleanup  cleanupProcedure = Cleanup_Delete 
)
virtualinherited

Sets an alternative buffer factory that is used for buffer allocation.

This use of this method is optional and intended for advanced use cases only.

If NULL is passed as buffer factory then the default buffer factory is used. Buffers are allocated when StartGrabbing is called. A buffer factory must not be deleted while it is attached to the camera object and it must not be deleted until the last buffer is freed. To free all buffers the grab needs to be stopped and all grab results must be released or destroyed.

Parameters
[in]pFactoryA pointer to a buffer factory.
[in]cleanupProcedureIf ownership is cleanupProcedure Cleanup_Delete, the passed factory is destroyed when no longer needed.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual void Pylon::CInstantCamera::SetCameraContext ( intptr_t  context)
virtualinherited

Sets a context that is attached to each grab result of the camera object on RetrieveResult().

This is useful when handling multiple cameras. It has nothing in common with the context passed to the stream grabber when queuing a buffer.

Error Safety:
Does not throw C++ exceptions.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual void Pylon::CInstantCamera::StartGrabbing ( EGrabStrategy  strategy = GrabStrategy_OneByOne,
EGrabLoop  grabLoopType = GrabLoop_ProvidedByUser 
)
virtualinherited

Starts the grabbing of images.

  • If a grab loop thread has been used in the last grab session, the grab loop thread context is joined with the caller's context.
  • If the Pylon device is not already open, it is opened by calling Open().
  • The configuration event OnGrabStart is fired. The notification of event handlers stops when an event call triggers an exception.
  • Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffers.
  • If the camera device parameter ChunkModeActive is enabled, the Instant Camera chunk parsing support is initialized.
  • If the Instant Camera parameter GrabCameraEvents is enabled, the Instant Camera event grabbing support is initialized.
  • The grabbing is started.
  • The AcquisitionStart command of the camera device is executed.
  • The configuration event OnGrabStarted is fired if the grab has been started successfully. The notification of event handlers stops when an event call triggers an exception.
  • If grabLoopType equals GrabLoop_ProvidedByInstantCamera, an additional grab loop thread is started calling RetrieveResult( GrabLoopThreadTimeout, grabResult) in a loop.
Parameters
[in]strategyThe grab strategy. See Pylon::EGrabStrategy for more information
[in]grabLoopTypeIf grabLoopType equals GrabLoop_ProvidedByInstantCamera, an additional grab loop thread is used to run the grab loop.
Precondition
  • A Pylon device is attached.
  • The stream grabber of the Pylon device is closed.
  • The grabbing is stopped.
  • The attached Pylon device supports grabbing.
  • Must not be called while holding the lock provided by GetLock() when using the grab loop thread.
Postcondition
  • The grabbing is started.
  • Grab-specific parameters of the camera object are locked, e.g. MaxNumBuffers.
  • If grabLoopType equals GrabLoop_ProvidedByInstantCamera, an additional grab loop thread is running that calls RetrieveResult( GrabLoopThreadTimeout, grabResult) in a loop. Images are processed by registered image event handlers.
  • Operating the stream grabber from outside the camera object will result in undefined behavior.
Error Safety:
The Instant Camera object is still valid after error. Open() may throw. Configuration event calls may throw. The grab implementation may throw. The grabbing is stopped with StopGrabbing() if the OnGrabStarted event call triggers an exception. Throws a C++ exception, if Upcoming Image grab strategy is used together with USB camera devices.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual void Pylon::CInstantCamera::StartGrabbing ( size_t  maxImages,
EGrabStrategy  strategy = GrabStrategy_OneByOne,
EGrabLoop  grabLoopType = GrabLoop_ProvidedByUser 
)
virtualinherited

Starts the grabbing for a maximum number of images.

Extends the StartGrabbing(EStrategy, EGrabLoop) by a number of images to grab. If the passed count of images has been reached, StopGrabbing is called automatically. The images are counted according to the grab strategy. Skipped images are not taken into account.

The amount of allocated buffers is reduced to maxImages when grabbing fewer images than according to the value of the MaxNumBuffer parameter and the grab strategy is GrabStrategy_OneByOne.

Parameters
[in]maxImagesThe count of images to grab. This value must be larger than zero.
[in]strategyThe grab strategy. See Pylon::InstantCamera::EStrategy for more information.
[in]grabLoopTypeIf grabLoopType equals GrabLoop_ProvidedByInstantCamera, an additional grab loop thread is used to run the grab loop.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual void Pylon::CInstantCamera::StopGrabbing ( )
virtualinherited

Stops the grabbing of images.

  • Nothing is done if the Instant Camera is not currently grabbing.
  • The configuration event OnGrabStop is fired. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
  • The AcquisitionStop command of the camera device is executed.
  • The grabbing is stopped.
  • All buffer queues of the Instant Camera are cleared.
  • The OnGrabStopped configuration event is fired if the grab has been stopped successfully. Possible C++ exceptions from event calls are caught and ignored. All event handlers are notified.
  • If the Instant Camera has been opened by StartGrabbing, it is closed by calling Close().
  • Grab-specific parameters of the camera object are unlocked, e.g. MaxNumBuffers.
Postcondition
  • The grabbing is stopped.
  • If the Pylon device has been opened by StartGrabbing and no other camera object service requires it to be open, it is closed.
  • Grab specific parameters of the camera object are unlocked, e.g. MaxNumBuffers.
Error Safety:
Does not throw C++ exceptions. Possible C++ exceptions are caught and ignored.
Thread Safety:
This method is synchronized using the lock provided by GetLock().
virtual bool Pylon::CInstantCamera::WaitForFrameTriggerReady ( unsigned int  timeoutMs,
ETimeoutHandling  timeoutHandling = TimeoutHandling_ThrowException 
)
virtualinherited

Actively waits until the the camera is ready to accept a frame trigger.

The implementation selects 'FrameTriggerWait' for the 'AcquisitionStatusSelector' and waits until the 'AcquisitionStatus' is true. If the above mentioned nodes are not available and the 'SoftwareTrigger' node is readable, the implementation waits for SoftwareTrigger.IsDone().

The WaitForFrameTriggerReady method does not work for A600 Firewire cameras.

Parameters
[in]timeoutMsThe timeout in ms for active waiting.
[in]timeoutHandlingIf timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout.
Returns
True if the camera can execute a frame trigger.
Precondition
The 'AcquisitionStatusSelector' node is writable and the 'AcquisitionStatus' node is readable or the 'SoftwareTrigger' node is readable. This depends on the used camera model.
Error Safety:
Accessing the camera registers may fail.
Thread Safety:
This method is synchronized using the lock provided by GetLock().

Member Data Documentation

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::AcquisitionStartStopExecutionEnable
inherited

If set, this will automatically execute AcquisitionStart when calling StartGrabbing and AcquisitionStop when calling StopGrabbing This option is enabled by default - Applies to: InstantCamera.

Visibility: Guru

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::ChunkNodeMapsEnable
inherited

Enables/disables the use of a chunk node map for each grab result Grab result chunk node maps can be disabled to save resources - Applies to: InstantCamera.

Visibility: Guru

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::ClearBufferModeEnable
inherited

If set, all buffers will be cleared (set to 0) before grabbing an image Note that this requires additional processing time per frame - Applies to: InstantCamera.

Visibility: Guru

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::GrabCameraEvents
inherited

Enables/disables the grabbing of camera events while images are grabbed Is writable when the camera object is closed - Applies to: InstantCamera.

Visibility: Expert

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::GrabLoopThreadPriority
inherited

The grab loop thread priority - Applies to: InstantCamera.

This value sets the absolute thread priority for the grab loop thread.

Visibility: Guru

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::GrabLoopThreadPriorityOverride
inherited

If enabled, the user can set a custom priority for the grab loop thread Otherwise, the priority of the newly created thread is not changed - Applies to: InstantCamera.

Visibility: Guru

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::GrabLoopThreadTimeout
inherited

A custom timeout for the grab loop thread's call to RetrieveResult RetrieveResult is configured to throw an exception on timeout, which will stop the grab session - Applies to: InstantCamera.

Visibility: Beginner

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::GrabLoopThreadUseTimeout
inherited

If enabled, the user can set a custom timeout for the grab loop thread's call to RetrieveResult RetrieveResult is configured to throw an exception on timeout, which will stop the grab session - Applies to: InstantCamera.

Visibility: Guru

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::InternalGrabEngineThreadPriority
inherited

The internal grab engine thread priority - Applies to: InstantCamera.

This value sets the absolute thread priority for the internal grab engine thread operating the stream grabber.

Visibility: Guru

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::InternalGrabEngineThreadPriorityOverride
inherited

If enabled, the user can set a custom priority for the internal grab engine thread operating the stream grabber Otherwise the priority defaults to 25 - Applies to: InstantCamera.

Visibility: Guru

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::MaxNumBuffer
inherited

The maximum number of buffers that are allocated and used for grabbing - Applies to: InstantCamera.

Visibility: Beginner

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::MaxNumGrabResults
inherited

The maximum number of grab results available at any time during a grab session This value can be limited to save resources Furthermore, it can be used to check that the grab results are returned correctly - Applies to: InstantCamera.

Visibility: Beginner

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::MaxNumQueuedBuffer
inherited

The maximum number of buffers that are queued in the stream grabber input queue - Applies to: InstantCamera.

Visibility: Beginner

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::MigrationModeActive
inherited

The migration mode is set up according to this setting at defined points e g , when the camera is opened - Applies to: InstantCamera.

Visibility: Guru

Pylon::IBooleanEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::MonitorModeActive
inherited

The camera object is set to monitor mode when enabled, e g when using the GigE multicast feature Is writable when the camera object is closed - Applies to: InstantCamera.

Visibility: Guru

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::NumEmptyBuffers
inherited

The number of empty buffers that are not used for grabbing yet - Applies to: InstantCamera.

Visibility: Expert

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::NumQueuedBuffers
inherited

The number of buffers queued at Low Level API stream grabber - Applies to: InstantCamera.

This is the number of buffers that are queued for grabbing in the stream grabber. The number is influenced by the number of available free buffers and the maximum number of buffers that can be queued. See also the MaxNumBuffer and MaxNumQueuedBuffer parameters.

This parameter can be used to check whether the number of buffers ready for grabbing is stable, which means that the image processing is fast enough to keep up with the rate of incoming images when using the GrabStrategy_OneByOne grab strategy.

Visibility: Expert

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::NumReadyBuffers
inherited

The number of grab result buffers in the output queue that are ready for retrieval - Applies to: InstantCamera.

Visibility: Expert

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::OutputQueueSize
inherited

The size of the grab result buffer output queue - Applies to: InstantCamera.

Visibility: Expert

Pylon::IIntegerEx& Basler_InstantCameraParams::CInstantCameraParams_Params_v6_1_0::StaticChunkNodeMapPoolSize
inherited

If larger than 0, a static chunk node map pool is used instead of dynamic chunk node map creation - Applies to: InstantCamera.

Visibility: Guru


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:56:59)