All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | List of all members
Pylon::CInstantCameraArray Class Reference

Supports grabbing with multiple camera devices. More...

#include <pylon/InstantCameraArray.h>

Public Types

typedef CInstantCamera InstantCamera_t
 The type of the camera class in the array.
 

Public Member Functions

 CInstantCameraArray ()
 Creates an Instant Camera Array of size 0. More...
 
 CInstantCameraArray (size_t numberOfCameras)
 Creates an Instant Camera Array. More...
 
virtual ~CInstantCameraArray ()
 Destroys the Instant Camera Array. More...
 
virtual void Initialize (size_t numberOfCameras)
 Initializes the array. More...
 
virtual bool IsPylonDeviceAttached () const
 Returns the attachment state of cameras in the array. More...
 
virtual bool IsCameraDeviceRemoved () const
 Returns the connection state of the camera devices used by the Instant Cameras in the array. More...
 
virtual void DestroyDevice ()
 Destroys the Pylon Devices that are attached to the Instant Cameras in the array. More...
 
virtual void DetachDevice ()
 Detaches all Pylon Devices that are attached to the Instant Cameras in the array. More...
 
virtual void Open ()
 Opens all cameras in the array. More...
 
virtual bool IsOpen () const
 Returns the open state of the cameras in the array. More...
 
virtual void Close ()
 Closes all cameras in the array. More...
 
virtual size_t GetSize () const
 Returns the size of the array. More...
 
virtual CInstantCameraoperator[] (size_t index)
 Retrieve a camera by index. More...
 
virtual const CInstantCameraoperator[] (size_t index) const
 Retrieve a camera by index. More...
 
virtual void StartGrabbing (EGrabStrategy strategy=GrabStrategy_OneByOne, EGrabLoop grabLoopType=GrabLoop_ProvidedByUser)
 Starts the grabbing of images for all cameras. 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...
 

Detailed Description

Supports grabbing with multiple camera devices.

Thread Safety:
The CInstantCameraArray class is not thread-safe.

Constructor & Destructor Documentation

Pylon::CInstantCameraArray::CInstantCameraArray ( )

Creates an Instant Camera Array of size 0.

Initialize() can be used to adjust the size of the array.

Error Safety:
Does not throw C++ exceptions.
Pylon::CInstantCameraArray::CInstantCameraArray ( size_t  numberOfCameras)

Creates an Instant Camera Array.

Calls Initialize() to adjust the size of the array.

Parameters
[in]numberOfCamerasThe number of cameras the array shall hold. Can be 0.

The index operator can be used to access the individual cameras for attaching a Pylon Device or for configuration.

Example:

// Create an array of two devices.
CInstantCamera array(2);
// Attach %Pylon Devices.
array[0].Attach( pDevice1);
array[1].Attach( pDevice2);
Error Safety:
Does not throw C++ exceptions, except when memory allocation fails.
virtual Pylon::CInstantCameraArray::~CInstantCameraArray ( )
virtual

Destroys the Instant Camera Array.

If a grab is in progress, it is stopped by calling StopGrabbing().

Error Safety:
Does not throw C++ exceptions.

Member Function Documentation

virtual void Pylon::CInstantCameraArray::Close ( )
virtual

Closes all cameras in the array.

Postcondition
All cameras in the array are closed.
Error Safety:
Does not throw C++ exceptions.
virtual void Pylon::CInstantCameraArray::DestroyDevice ( )
virtual

Destroys the Pylon Devices that are attached to the Instant Cameras in the array.

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.
Postcondition
No Pylon Devices are attached to the cameras in the array.
Error Safety:
Does not throw C++ exceptions.
virtual void Pylon::CInstantCameraArray::DetachDevice ( )
virtual

Detaches all Pylon Devices that are attached to the Instant Cameras in the array.

Postcondition
  • No Pylon Devices are attached to the cameras in the array.
  • The ownership of the Pylon Devices goes to the caller who is responsible for destroying the Pylon Devices.
Error Safety:
Does not throw C++ exceptions.
virtual size_t Pylon::CInstantCameraArray::GetSize ( ) const
virtual

Returns the size of the array.

Error Safety:
Does not throw C++ exceptions.
virtual void Pylon::CInstantCameraArray::Initialize ( size_t  numberOfCameras)
virtual

Initializes the array.

  • If a grab is in progress, it is stopped by calling StopGrabbing().
  • All cameras of the array are destroyed.
  • A new set of cameras is created. No Pylon Devices are attached.
  • The camera context values are set to the index of the camera in the array using CInstantCamera::SetCameraContext.

The index operator can be used to access the individual cameras for attaching a Pylon Device or for configuration.

Parameters
[in]numberOfCamerasThe number of cameras the array shall hold.
Error Safety:
Does not throw C++ exceptions, except when memory allocation fails.
virtual bool Pylon::CInstantCameraArray::IsCameraDeviceRemoved ( ) const
virtual

Returns the connection state of the camera devices used by the Instant Cameras in the array.

The device removal is only detected if the Instant Cameras and therefore the attached Pylon Devices are open.

The Pylon Device is not operable after this event. 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 InstantCamera::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 for any camera in the array has been detected.
Error Safety:
Does not throw C++ exceptions.
virtual bool Pylon::CInstantCameraArray::IsGrabbing ( ) const
virtual

Returns state of grabbing.

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

Returns
Returns true if still grabbing.
Error Safety:
Does not throw C++ exceptions.
virtual bool Pylon::CInstantCameraArray::IsOpen ( ) const
virtual

Returns the open state of the cameras in the array.

Error Safety: Does not throw C++ exceptions.
Returns
Returns true if all cameras in the array are open. False is returned if the size of the array is 0.
virtual bool Pylon::CInstantCameraArray::IsPylonDeviceAttached ( ) const
virtual

Returns the attachment state of cameras in the array.

Returns
True if all cameras in the array have a Pylon Device attached. False is returned if the size of the array is 0.
Error Safety:
Does not throw C++ exceptions.
virtual void Pylon::CInstantCameraArray::Open ( )
virtual

Opens all cameras in the array.

Open is called for all cameras. See CInstantCamera::Open() for more information.

Precondition
  • The size of the array is larger than 0.
  • All devices are attached.
Postcondition
The cameras are open.
Error Safety:
If one camera throws an exception, all cameras are closed by calling Close().
virtual CInstantCamera& Pylon::CInstantCameraArray::operator[] ( size_t  index)
virtual

Retrieve a camera by index.

Precondition
The index is smaller than GetSize();
Error Safety:
Throws an exception if the index is not valid.
virtual const CInstantCamera& Pylon::CInstantCameraArray::operator[] ( size_t  index) const
virtual

Retrieve a camera by index.

Precondition
The index is smaller than GetSize();
Error Safety:
Throws an exception if the index is not valid.
virtual bool Pylon::CInstantCameraArray::RetrieveResult ( unsigned int  timeoutMs,
CGrabResultPtr 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 the grabbing is not started, the method returns immediately false.
  • If GrabStrategy_UpcomingImage strategy: RetrieveResult is called for a camera. Cameras are processed using a round-robin strategy.
  • If GrabStrategy_OneByOne, GrabStrategy_LatestImageOnly or GrabStrategy_LatestImages strategy: Pending images or camera events are retrieved. Cameras are processed using a round-robin strategy.
  • If GrabStrategy_OneByOne, GrabStrategy_LatestImageOnly or GrabStrategy_LatestImages strategy: Wait for a grab result if it is not yet available. Camera events are handled.

The camera array index is assigned to the context value of the instant camera when Initialize() is called. This context value is attached to the result when the result is retrieved and can be obtained using the grab result method GrabResultData::GetCameraContext(). The context value can be used to associate the result with the camera from where it originated.

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
The preconditions for calling StartGrabbing() are met for every camera in the array.
Postcondition
  • If successful, one image is removed from the output queue of a camera and is returned in the grabResult parameter.
  • If not successful, an empty grab result is returned in the grabResult parameter.
Error Safety:
The Instant Camera Array object is still valid after error. The grabbing is stopped by calling StopGrabbing() if an exception is thrown.
virtual void Pylon::CInstantCameraArray::StartGrabbing ( EGrabStrategy  strategy = GrabStrategy_OneByOne,
EGrabLoop  grabLoopType = GrabLoop_ProvidedByUser 
)
virtual

Starts the grabbing of images for all cameras.

  • StartGrabbing is called for all cameras with the provided parameters, see CInstantCamera::StartGrabbing() for more information.
  • The grabbing is started.
  • The starting position for retrieving results is set to the first camera.
Parameters
[in]strategyThe grab strategy, see Pylon::InstantCamera::EStrategy for more information.
[in]grabLoopTypeIndicates using the internal grab thread of the camera.
Precondition
  • The size of the array is larger than 0.
  • All devices are attached.
  • The grabbing is stopped.
  • The preconditions for calling StartGrabbing() are met for every camera in the array.
Postcondition
The grabbing is started.
Error Safety:
The camera objects may throw an exception. The grabbing is stopped calling StopGrabbing() in this case.
virtual void Pylon::CInstantCameraArray::StopGrabbing ( )
virtual

Stops the grabbing of images.

The grabbing is stopped. StopGrabbing is called for all cameras. See CInstantCamera::StopGrabbing() for more information.

Postcondition
The grabbing is stopped.
Error Safety:
Does not throw C++ exceptions.
Thread Safety:
Can be called while one other thread is polling RetrieveResult() in a IsGrabbing()/RetrieveResult() loop to stop grabbing.

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

pylon 5.0.5
Copyright © 2006-2016 Basler AG (Thu Aug 11 2016 18:01:28)