Helper class to give plugin developers an easy access to cameras in other threads. More...

#include <pluginThreadCtrl.h>

Inheritance diagram for ito::DataIOThreadCtrl:

Public Member Functions
	DataIOThreadCtrl ()
	default constructor. No dataIO instance is currently under control.

	DataIOThreadCtrl (const ito::ParamBase &pluginParameter, ito::RetVal *retval=NULL)
	Creates the control object for a dataIO plugin instance.

	DataIOThreadCtrl (ito::AddInDataIO plugin, ito::RetVal retval=NULL)
	Creates the control object for a dataIO plugin instance.

	DataIOThreadCtrl (const DataIOThreadCtrl &other)
	copy constructor. The reference counter of the covered plugin by other will be incremented another time.

virtual	~DataIOThreadCtrl ()
	destructor. Decrements the reference counter of the covered plugin and deletes it, if it drops to zero.

ito::RetVal	startDevice (int timeOutMS=PLUGINWAIT)

ito::RetVal	stopDevice (int timeOutMS=PLUGINWAIT)

ito::RetVal	acquire (const int trigger=0, int timeOutMS=PLUGINWAIT)

ito::RetVal	getVal (ito::DataObject &dObj, int timeOutMS=PLUGINWAIT)

ito::RetVal	copyVal (ito::DataObject &dObj, int timeOutMS=PLUGINWAIT)

ito::RetVal	enableAutoGrabbing (int timeOutMS=PLUGINWAIT)

ito::RetVal	disableAutoGrabbing (int timeOutMS=PLUGINWAIT)

ito::RetVal	setAutoGrabbingInterval (QSharedPointer< int > interval, int timeOutMS=PLUGINWAIT)

bool	getAutoGrabbing ()

ito::RetVal	getImageParams (int &bpp, int &sizex, int &sizey, int timeOutMS=PLUGINWAIT)

Public Member Functions inherited from ito::PluginThreadCtrl
	PluginThreadCtrl ()
	default constructor. No plugin instance is currently under control.

	PluginThreadCtrl (const ito::ParamBase &pluginParameter, ito::RetVal *retval=NULL)
	Creates the control object for a plugin instance.

	PluginThreadCtrl (ito::AddInBase plugin, ito::RetVal retval=NULL)
	Creates the control object for a plugin instance.

	PluginThreadCtrl (const PluginThreadCtrl &other)
	copy constructor. The reference counter of the covered plugin by other will be incremented another time.

virtual	~PluginThreadCtrl ()
	destructor. Decrements the reference counter of the covered plugin and deletes it, if it drops to zero.

PluginThreadCtrl &	operator= (const PluginThreadCtrl &other)
	assignment operator. Gets control over the plugin currently covered by other. Decrements the reference counter of the former plugin and increments it of the plugin controlled by other.

ito::RetVal	getParam (ito::Param &val, int timeOutMS=PLUGINWAIT)

ito::RetVal	setParam (ito::ParamBase val, int timeOutMS=PLUGINWAIT)

ito::RetVal	waitForSemaphore (int timeOutMS=PLUGINWAIT)

Additional Inherited Members
Protected Attributes inherited from ito::PluginThreadCtrl
ito::AddInBase *	m_pPlugin

ItomSharedSemaphoreLocker	m_semaphoreLocker

Detailed Description

Helper class to give plugin developers an easy access to cameras in other threads.

The DataIOThreadCtrl-Class can be used in filters and algorithms when a camera (framegrabber) or other dataIO plugin should be controlled by another thread. To create this controlling instance, at first, create an instance of the dataIO plugin itself, then, pass it to the constructor of DataIOThreadCtrl. In the following example, an instance of DummyGrabber is passed as first mandatory argument to the init method of your plugin. You would like to create an easy thread control wrapper around this camera plugin:

ito::RetVal retval;
 
//first alternative
ito::AddInDataIO *cam = paramsMand->at(0).getVal<ito::AddInDataIO*>();
DataIOThreadCtrl camSave(cam, &retval);
 
//second alternative
DataIOThreadCtrl camSave(paramsMand->at(0), &retval);

Using this class, all main methods of the dataIO plugin can be directly called with an optional timeout value (in ms). The thread control, timeout checks... is then done by this helper class.

To start the image acquisition of 'camSave', you have to call startDevice once. At the end of any acquisition call stopDevice. Every single image is acquired using acquire, while the acquired image data is obtained via a dataObject calling getVal or copyVal.

The acquire / getVal combination returns a shallow copy of the internal dataObject of the grabber. Therefore, the content of the returned shallow copy might automatically change upon the next acquisition. The acquire / copyVal combination returns a deep copy of the grabber memory to the defined external dataObject.

retval += camSave.startDevice(2000);
if (!retval.containsError())
{
ito::DataObject image;
retval += camSave.setParam(ito::ParamBase("integration_time", ito::ParamBase::Double, 0.1));
for (int i = 0; i < 10; ++i)
{
    retval += camSave.acquire();
    retval += camSave.getVal(image);
}
retval += camSave.stopDevice();
}

Constructor & Destructor Documentation

◆ DataIOThreadCtrl() [1/2]

ito::DataIOThreadCtrl::DataIOThreadCtrl	(	const ito::ParamBase &	pluginParameter,
		ito::RetVal *	retval = NULL )

Creates the control object for a dataIO plugin instance.

This implementation gets the controlled instance from a ito::ParamBase object of param type ito::ParamBase::HWRef. Use this version, if the controlled plugin is passed to an algorithm or other plugin via a vector of mandatory or optional parameters in terms of ito::ParamBase objects.

This constructor increments the reference of the controlled plugin such that the plugin is not deleted until the reference has been decremented in the destructor of this class.

Parameters

pluginParameter	is a plugin parameter of type ito::ParamBase::HWRef.
retval	is an optional pointer to ito::RetVal. An error is set to this retval if the given plugin is no valid dataIO plugin instance.

◆ DataIOThreadCtrl() [2/2]

ito::DataIOThreadCtrl::DataIOThreadCtrl	(	ito::AddInDataIO *	plugin,
		ito::RetVal *	retval = NULL )

Creates the control object for a dataIO plugin instance.

This implementation gets the controlled instance from the real pointer to a ito::AddInDataIO instance.

This constructor increments the reference of the controlled plugin such that the plugin is not deleted until the reference has been decremented in the destructor of this class.

Parameters

plugin	is the pointer to the controlled plugin.
retval	is an optional pointer to ito::RetVal. An error is set to this retval if the given plugin is no valid dataIO plugin instance.

Member Function Documentation

◆ acquire()

ito::RetVal ito::DataIOThreadCtrl::acquire	(	const int	trigger = 0,
		int	timeOutMS = PLUGINWAIT )

Trigger an exposure and return before image is done

\detail The acquire()-function triggers a new exposure of the camera and returns afterwards. It can only be executed after startDevice(). The function does not wait until the exposure is done. This is performed by the getVal or copyVal-method.

Parameters

[in]	trigger	A currently not implemented constant to define trigger-modes during exposure of the camera
[in]	timeOutMS	TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::startDevice, DataIOThreadCtrl::getVal, DataIOThreadCtrl::copyVal

◆ copyVal()

ito::RetVal ito::DataIOThreadCtrl::copyVal	(	ito::DataObject &	dObj,
		int	timeOutMS = PLUGINWAIT )

Get a deep-copy of the dataObject

\detail The copyVal function is used to wait until an exposure is finished. Than it gives a deep copy of the inner dataObject within the grabber to the dObj-argument. Before the copyVal()-function can be used an acquire() is necessary. If the content of dObj do not need to be deepcopied to another object and will not be overwritten after the next acquire() - getVal() combination.

Parameters

	[in\|out]	dObj IN: an dataObject \| OUT: an dataObject containing an shallow copy of the last captured image
[in]	timeOutMS	TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::acquire, DataIOThreadCtrl::getVal, DataIOThreadCtrl::startDevice

< Get a deep-copy of the dataObject

◆ disableAutoGrabbing()

ito::RetVal ito::DataIOThreadCtrl::disableAutoGrabbing ( int timeOutMS = PLUGINWAIT )

Disables the timer for auto grabbing

\detail Disables the timer for auto grabbing (live image).

Parameters

[in] timeOutMS TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::startDevice, DataIOThreadCtrl::getVal, DataIOThreadCtrl::copyVal

◆ enableAutoGrabbing()

ito::RetVal ito::DataIOThreadCtrl::enableAutoGrabbing ( int timeOutMS = PLUGINWAIT )

Enables the timer for auto grabbing

\detail Enables the timer for auto grabbing (live image), if any live image has signed on.

Parameters

[in] timeOutMS TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::startDevice, DataIOThreadCtrl::getVal, DataIOThreadCtrl::copyVal

◆ getAutoGrabbing()

bool ito::DataIOThreadCtrl::getAutoGrabbing ( )

Returns the state of m_autoGrabbingEnabled; consider this method as final

\detail The getAutoGrabbing function is used to get the auto grabbing setting.

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::acquire, DataIOThreadCtrl::startDevice, DataIOThreadCtrl::copyVal

◆ getImageParams()

ito::RetVal ito::DataIOThreadCtrl::getImageParams	(	int &	bpp,
		int &	sizex,
		int &	sizey,
		int	timeOutMS = PLUGINWAIT )

Combined function to get the most important camera features

\detail Get the most important parameter of the camera.

Parameters

[out]	bpp	Number of Bits this camera grabs
[out]	xsize	Size of the camera in x (cols)
[out]	ysize	Size of the camera in y (rows)

Returns: retOk or retError

◆ getVal()

ito::RetVal ito::DataIOThreadCtrl::getVal	(	ito::DataObject &	dObj,
		int	timeOutMS = PLUGINWAIT )

Get a shallow-copy of the dataObject

\detail The getVal function is used to wait until an exposure is finished. Than it gives a shallow copy of the inner dataObject within the grabber to the dObj-argument. Before the getVal()-function can be used an acquire() is necessary. If the content of dObj is not deepcopied to another object, the data is lost after the next acquire() - getVal() combination and overwritten by the newly captured image.

Parameters

	[in\|out]	dObj IN: an dataObject \| OUT: an dataObject containing an shallow copy of the last captured image
[in]	timeOutMS	TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::acquire, DataIOThreadCtrl::startDevice, DataIOThreadCtrl::copyVal

< Get a shallow-copy of the dataObject

◆ setAutoGrabbingInterval()

ito::RetVal ito::DataIOThreadCtrl::setAutoGrabbingInterval	(	QSharedPointer< int >	interval,
		int	timeOutMS = PLUGINWAIT )

Sets a new interval for the auto-grabbing timer (in ms).

\detail Sets a new interval for the auto-grabbing timer (in ms). If interval <= 0 is passed, nothing is changed, but the current interval is returned. This method does not enable or disable the timer.

Parameters

[in]	interval	Timer (in ms)
[in]	timeOutMS	TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::startDevice, DataIOThreadCtrl::getVal, DataIOThreadCtrl::copyVal

◆ startDevice()

ito::RetVal ito::DataIOThreadCtrl::startDevice ( int timeOutMS = PLUGINWAIT )

Set camera active

\detail Every capture procedure starts with the startDevice() to set the camera active and is ended with stopDevice().

Parameters

[in] timeOutMS TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::stopDevice, DataIOThreadCtrl::acquire, DataIOThreadCtrl::getVal, DataIOThreadCtrl::copyVal

◆ stopDevice()

ito::RetVal ito::DataIOThreadCtrl::stopDevice ( int timeOutMS = PLUGINWAIT )

Set camera deactivate

\detail Every capture procedure starts with the startDevice() to set the camera active and is ended with stopDevice().

Parameters

[in] timeOutMS TimeOut for the semaphore-wait

Returns: retOk or retError

See also: DataIOThreadCtrl::startDevice, DataIOThreadCtrl::acquire, DataIOThreadCtrl::getVal, DataIOThreadCtrl::copyVal

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

C:/Workspace/itom_development_VS2019_Qt5.15.2_x64/itomProject/itom/common/pluginThreadCtrl.h
C:/Workspace/itom_development_VS2019_Qt5.15.2_x64/itomProject/itom/common/sources/pluginThreadCtrl.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DataIOThreadCtrl() [1/2]

◆ DataIOThreadCtrl() [2/2]

Member Function Documentation

◆ acquire()

◆ copyVal()

◆ disableAutoGrabbing()

◆ enableAutoGrabbing()

◆ getAutoGrabbing()

◆ getImageParams()

◆ getVal()

◆ setAutoGrabbingInterval()

◆ startDevice()

◆ stopDevice()