Provides convenient access to a camera device. More...
#include <pylon/InstantCamera.h>
Public Types | |
typedef CInstantCamera | InstantCamera_t |
The type of the camera class. | |
typedef IPylonDevice | IPylonDevice_t |
Low Level API: Interface for camera objects. | |
typedef Pylon::CDeviceInfo | DeviceInfo_t |
Holds information about an enumerated device. | |
typedef CConfigurationEventHandler | ConfigurationEventHandler_t |
The generic configuration event handler class. | |
typedef CImageEventHandler | ImageEventHandler_t |
The generic image event handler class. | |
typedef CCameraEventHandler | CameraEventHandler_t |
The generic image event handler class. | |
typedef CGrabResultData | GrabResultData_t |
The generic grab result data. | |
typedef CGrabResultPtr | GrabResultPtr_t |
The generic grab result smart pointer. | |
Public Member Functions | |
CInstantCamera () | |
Creates an Instant Camera object with no attached Pylon device. More... | |
CInstantCamera (IPylonDevice *pDevice, ECleanup cleanupProcedure=Cleanup_Delete) | |
Creates an Instant Camera object and calls Attach(). More... | |
virtual | ~CInstantCamera () |
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 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 void | DestroyDevice () |
Destroys the attached Pylon device. More... | |
virtual IPylonDevice * | DetachDevice () |
Detaches an attached Pylon device. More... | |
virtual void | Open () |
Opens the attached Pylon device. More... | |
virtual bool | IsOpen () const |
Returns the open state of the Pylon device. More... | |
virtual void | Close () |
Closes the attached Pylon device. 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 WaitObject & | GetGrabResultWaitObject () |
Provides access to a wait object indicating available grab results. More... | |
virtual const WaitObject & | GetGrabStopWaitObject () |
Provides access to a wait object indicating that the grabbing has stopped. More... | |
virtual const WaitObject & | GetCameraEventWaitObject () |
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 const CDeviceInfo & | GetDeviceInfo () const |
Provides access to the device info object of the attached Pylon device or an empty one. More... | |
virtual GenApi::INodeMap & | GetNodeMap () |
Provides access to the node map of the camera device. More... | |
virtual GenApi::INodeMap & | GetTLNodeMap () |
Provides access to the transport layer node map of the attached Pylon device. More... | |
virtual GenApi::INodeMap & | GetStreamGrabberNodeMap () |
Provides access to the stream grabber node map of the attached Pylon device. More... | |
virtual GenApi::INodeMap & | GetEventGrabberNodeMap () |
Provides access to the event grabber node map of the attached Pylon device. More... | |
virtual GenApi::INodeMap & | GetInstantCameraNodeMap () |
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... | |
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 | |
Root - Instant camera parameters. | |
GenApi::IInteger & | MaxNumBuffer |
The maximum number of buffers that are allocated and used for grabbing. More... | |
GenApi::IInteger & | MaxNumQueuedBuffer |
The maximum number of buffers that are queued in the stream grabber input queue. More... | |
GenApi::IInteger & | MaxNumGrabResults |
The maximum number of grab results available at any time during a grab session. More... | |
GenApi::IBoolean & | ChunkNodeMapsEnable |
Enables/disables the use of a chunk node map for each grab result. More... | |
GenApi::IInteger & | StaticChunkNodeMapPoolSize |
If larger than 0, a static chunk node map pool is used instead of dynamic chunk node map creation. More... | |
GenApi::IBoolean & | GrabCameraEvents |
Enables/disables the grabbing of camera events while images are grabbed. More... | |
GenApi::IBoolean & | MonitorModeActive |
The camera object is set to monitor mode when enabled, e.g. More... | |
GenApi::IInteger & | NumQueuedBuffers |
The number of buffers queued at Low Level API stream grabber. More... | |
GenApi::IInteger & | NumReadyBuffers |
The number of grab result buffers in the output queue that are ready for retrieval. More... | |
GenApi::IInteger & | NumEmptyBuffers |
The number of empty buffers that are not used for grabbing yet. More... | |
GenApi::IInteger & | OutputQueueSize |
The size of the grab result buffer output queue. More... | |
InternalGrabEngineThread - Parameters of the internal grab engine thread. | |
GenApi::IBoolean & | InternalGrabEngineThreadPriorityOverride |
If enabled, the user can set a custom priority for the internal grab engine thread operating the stream grabber. More... | |
GenApi::IInteger & | InternalGrabEngineThreadPriority |
The internal grab engine thread priority. More... | |
GrabLoopThread - Parameters of the optional grab loop thread. | |
GenApi::IBoolean & | GrabLoopThreadUseTimeout |
If enabled, the user can set a custom timeout for the grab loop thread's call to RetrieveResult. More... | |
GenApi::IInteger & | GrabLoopThreadTimeout |
A custom timeout for the grab loop thread's call to RetrieveResult. More... | |
GenApi::IBoolean & | GrabLoopThreadPriorityOverride |
If enabled, the user can set a custom priority for the grab loop thread. More... | |
GenApi::IInteger & | GrabLoopThreadPriority |
The grab loop thread priority. More... | |
Protected Member Functions | |
virtual IPylonDevice * | GetDevice () |
Provides access to the attached Pylon device. More... | |
CLock & | GetLock () |
Provides access to the lock used for synchronizing the access to the camera. More... | |
Provides convenient access to a camera device.
Pylon::CInstantCamera::CInstantCamera | ( | ) |
Creates an Instant Camera object with no attached Pylon device.
Pylon::CInstantCamera::CInstantCamera | ( | IPylonDevice * | pDevice, |
ECleanup | cleanupProcedure = Cleanup_Delete |
||
) |
Creates an Instant Camera object and calls Attach().
See Attach() for more information.
[in] | pDevice | The Pylon device to attach. |
[in] | cleanupProcedure | If cleanupProcedure equals Cleanup_Delete, the Pylon device is destroyed when the Instant Camera object is destroyed. |
|
virtual |
Destroys an Instant Camera object.
Calls Attach( NULL) for destroying or removing a Pylon device depending on the passed cleanup procedure.
|
virtual |
Attaches a Pylon device to the Instant Camera.
[in] | pDevice | The Pylon device to attach. |
[in] | cleanupProcedure | If cleanupProcedure equals Cleanup_Delete, the Pylon device is destroyed when the Instant Camera object is destroyed. |
|
virtual |
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.
|
virtual |
Closes the attached Pylon device.
|
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.
[in] | cameraEventHandler | The registered receiver of camera events. |
[in] | nodeName | The name of the event data node updated on camera event, e.g. "ExposureEndEventTimestamp" for exposure end event. |
|
virtual |
Removes a configurator from the list of registered configurator objects.
If the configurator is not found, nothing is done.
[in] | configurator | The registered receiver of configuration events. |
|
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.
[in] | imageEventHandler | The registered receiver of configuration events. |
|
virtual |
Destroys the attached Pylon device.
|
virtual |
Detaches an attached Pylon device.
|
virtual |
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;
Pylon::CSoftwareTriggerConfiguration
selects the correct trigger when the Instant Camera is opened.timeoutHandling
is TimeoutHandling_ThrowException.
|
virtual |
Returns the context that is attached to each grab result of the camera object.
|
virtual |
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.
|
protectedvirtual |
Provides access to the attached Pylon device.
|
virtual |
Provides access to the device info object of the attached Pylon device or an empty one.
|
virtual |
Provides access to the event grabber node map of the attached Pylon device.
|
virtual |
Provides access to a wait object indicating available grab results.
|
virtual |
Provides access to a wait object indicating that the grabbing has stopped.
|
virtual |
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.
|
protected |
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:
|
virtual |
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.
|
virtual |
Deprecated: This method has been deprecated.
Use the NumQueuedBuffers parameter instead.
VersionInfo Pylon::CInstantCamera::GetSfncVersion | ( | ) | const |
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.
|
virtual |
Provides access to the stream grabber node map of the attached Pylon device.
|
virtual |
Provides access to the transport layer node map of the attached Pylon device.
|
virtual |
Grabs one image.
The following code shows a simplified version of what is done (happy path):
GrabOne() can be used to together with the CAcquireSingleFrameConfiguration.
[in] | timeoutMs | A timeout value in ms for waiting for a grab result, or the INFINITE value. |
[out] | grabResult | Receives the grab result. |
[in] | timeoutHandling | If timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout. |
|
virtual |
Returns the ownership of the attached Pylon device.
|
virtual |
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.
|
virtual |
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.
|
virtual |
Returns the connection state of the camera device.
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 InstantCamera::DeviceDestroy(). The access to the Pylon device can be protected using the lock provided by GetLock(), e.g. when accessing parameters.
|
virtual |
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.
|
virtual |
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.
|
virtual |
Returns state of grabbing.
The camera object is grabbing after a successful call to StartGrabbing() until StopGrabbing() is called.
|
virtual |
Returns the open state of the Pylon device.
|
virtual |
Returns the Pylon device attached state of the Instant Camera object.
|
virtual |
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.
|
virtual |
Opens the attached Pylon device.
|
virtual |
Adds an camera event handler to the list of registered camera event handler objects.
pCameraEventHandler
is not NULL, it is appended to the list of camera event handlers. [in] | pCameraEventHandler | The receiver of camera events. |
[in] | nodeName | The name of the event data node updated on camera event, e.g. "ExposureEndEventTimestamp" for exposure end event. |
[in] | userProvidedId | This 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] | mode | Indicates how to register the new cameraEventHandler. |
[in] | cleanupProcedure | If cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed. |
[in] | availability | If 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.
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.
|
virtual |
Adds a configurator to the list of registered configurator objects.
pConfigurator
is not NULL, it is appended to the list of configurators. [in] | pConfigurator | The receiver of configuration events. |
[in] | mode | Indicates how to register the new configurator. |
[in] | cleanupProcedure | If cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed. |
|
virtual |
Adds an image event handler to the list of registered image event handler objects.
pImageEventHandler
is not NULL, it is appended to the list of image event handlers. [in] | pImageEventHandler | The receiver of image events. |
[in] | mode | Indicates how to register the new imageEventHandler. |
[in] | cleanupProcedure | If cleanupProcedure equals Cleanup_Delete, the passed event handler is deleted when no longer needed. |
|
virtual |
Retrieves a grab result according to the strategy, waits if it is not yet available.
It needs to be checked whether the grab represented by the grab result has been successful, see CGrabResultData::GrabSucceeded().
[in] | timeoutMs | A timeout value in ms for waiting for a grab result, or the INFINITE value. |
[out] | grabResult | Receives the grab result. |
[in] | timeoutHandling | If timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout. |
|
virtual |
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.
[in] | pFactory | A pointer to a buffer factory. |
[in] | cleanupProcedure | If ownership is cleanupProcedure Cleanup_Delete, the passed factory is destroyed when no longer needed. |
|
virtual |
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.
|
virtual |
Starts the grabbing of images.
[in] | strategy | The grab strategy. See Pylon::EGrabStrategy for more information |
[in] | grabLoopType | If grabLoopType equals GrabLoop_ProvidedByInstantCamera, an additional grab loop thread is used to run the grab loop. |
|
virtual |
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.
[in] | maxImages | The count of images to grab. This value must be larger than zero. |
[in] | strategy | The grab strategy. See Pylon::InstantCamera::EStrategy for more information. |
[in] | grabLoopType | If grabLoopType equals GrabLoop_ProvidedByInstantCamera, an additional grab loop thread is used to run the grab loop. |
|
virtual |
Stops the grabbing of images.
|
virtual |
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.
[in] | timeoutMs | The timeout in ms for active waiting. |
[in] | timeoutHandling | If timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout. |
|
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.
Visibility = Guru
|
inherited |
Enables/disables the grabbing of camera events while images are grabbed.
Is writable when the camera object is closed.
Visibility = Expert
|
inherited |
The grab loop thread priority.
This value sets the absolute thread priority for the grab loop thread.
Visibility = Guru
|
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.
Visibility = Guru
|
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.
Visibility = Beginner
|
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.
Visibility = Guru
|
inherited |
The internal grab engine thread priority.
This value sets the absolute thread priority for the internal grab engine thread operating the stream grabber.
Visibility = Guru
|
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.
Visibility = Guru
|
inherited |
The maximum number of buffers that are allocated and used for grabbing.
Visibility = Beginner
|
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.
Visibility = Beginner
|
inherited |
The maximum number of buffers that are queued in the stream grabber input queue.
Visibility = Beginner
|
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.
Visibility = Guru
|
inherited |
The number of empty buffers that are not used for grabbing yet.
Visibility = Expert
|
inherited |
The number of buffers queued at Low Level API stream grabber.
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
|
inherited |
The number of grab result buffers in the output queue that are ready for retrieval.
Visibility = Expert
|
inherited |
The size of the grab result buffer output queue.
Visibility = Expert
|
inherited |
If larger than 0, a static chunk node map pool is used instead of dynamic chunk node map creation.
Visibility = Guru