FunctionInterface Class Reference

The function interface to devices supported by this interface. More...

#include <mvIMPACT_acquire.h>

Public Member Functions
int	acquisitionStart (void) const
	Manually starts the acquisition engine of this device driver instance.
int	acquisitionStop (void) const
	Manually stops the acquisition engine of this device driver instance.
int	createImageRequestControl (const std::string &name, const std::string &parent="Base", ComponentList *pNewRequestControl=0)
	Creates a new mvIMPACT::acquire::ImageRequestControl object.
int	createSetting (const std::string &name, const std::string &parent="Base", ComponentList *pNewSetting=0)
	Creates a new setting.
int	deleteSetting (const std::string &name, TStorageLocation storageLocation=slNative, TScope scope=sGlobal) const
	Deletes a setting from the specified location.
int	deleteSettingFromStack (void)
	Deletes the last setting from the setting stack.
	FunctionInterface (const FunctionInterface &src)
	Constructs a new mvIMPACT::acquire::FunctionInterface from an existing one.
	FunctionInterface (Device *pDev, RequestFactory *pRequestFactory=0)
	Constructs a new function interface for the device pointed to by pDev.
const std::vector< std::string > &	getAvailableImageRequestControls (void) const
	Returns the names of the image request controls available for this mvIMPACT::acquire::Device.
const std::vector< std::string > &	getAvailableSettings (void) const
	Returns the names of the settings available for this mvIMPACT::acquire::Device.
int	getCurrentCaptureBufferLayout (ImageRequestControl &imageRequestControl, int &size, int &alignment) const
	Returns information about the current capture buffer requirements.
int	getCurrentCaptureBufferLayout (ImageRequestControl &imageRequestControl, Request **ppRequest=0, int *pAlignment=0) const
	Returns information about the current capture buffer requirements.
Request *	getRequest (int nr) const
	Returns a pointer to the desired mvIMPACT::acquire::Request.
ComponentList	getSetting (const std::string &name) const
	Returns a mvIMPACT::acquire::ComponentList object to a setting with a specified name.
int	imageRequestConfigure (const Request *pRequest) const
	Sets a request into configuration mode.
int	imageRequestReset (int requestCtrlNr, int mode) const
	Deletes all requests currently queued for the specified mvIMPACT::acquire::ImageRequestControl.
int	imageRequestResultQueueElementCount (int queueNr=0) const
	Returns the number of mvIMPACT::acquire::Request objects in the result queue .
int	imageRequestSingle (ImageRequestControl *pImageRequestControl=0, int *pRequestUsed=0) const
	Sends an image request to the mvIMPACT::acquire::Device driver.
int	imageRequestUnlock (int nr) const
	Unlocks the request for the driver again.
int	imageRequestWaitFor (int timeout_ms, int queueNr=0) const
	Waits for a request object to become ready.
bool	isRequestNrValid (int nr) const
	Check if nr specifies a valid mvIMPACT::acquire::Request.
int	isSettingAvailable (const std::string &name, TStorageLocation storageLocation=slNative, TScope scope=sGlobal) const
	Checks if a certain setting is available under the specified location.
int	loadAndDeleteSettingFromStack (void)
	loads the last setting from the setting stack and then removes this setting from the stack.
int	loadSetting (const std::string &name, TStorageFlag storageFlags=sfNative, TScope scope=sGlobal) const
	Loads a previously stored setting.
int	loadSettingFromDefault (TScope scope=sUser) const
	Loads the default settings.
int	loadSettingFromStack (void)
	loads the last setting from the setting stack.
FunctionInterface &	operator= (const FunctionInterface &rhs)
	Allows assignments of mvIMPACT::acquire::FunctionInterface objects.
unsigned int	requestCount (void) const
	Returns the number of available request objects.
int	saveCurrentSettingOnStack (TStorageFlag storageFlags=sfRAM)
	Saves the current setting on the setting stack.
int	saveSetting (const std::string &name, TStorageFlag storageFlags=sfNative, TScope scope=sGlobal) const
	Stores the current settings.
int	saveSettingToDefault (TScope scope=sUser) const
	Stores the current settings under a default location.
void	updateRequests (void) const
	Updates the internal cache for request objects.
virtual	~FunctionInterface (void)
	Class destructor.

Detailed Description

The function interface to devices supported by this interface.

This class contains all the basic functions needed when working with a device. There are not too many functions as most data will be represented by 'properties' in other classes of this module, keeping the set of functions to remember rather small. To construct a new function interface, a pointer to a mvIMPACT::acquire::Device object must be passed to the constructor of mvIMPACT::acquire::FunctionInterface. In order to work with the mvIMPACT::acquire::FunctionInterface object the device needs to be initialized, so if the mvIMPACT::acquire::Device object pointed to by pDev in the constructors parameter list hasn't been opened already the constructor will try to do that.

Please refer to one of the examples listed below to get an idea on how to use this class for data acquisition:

• SingleCapture.cpp
• ContinuousCapture.cpp

Examples

CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.linux.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureAllFormats.win32.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamCommonSettingsUsage.legacy.cpp, GenICamInterfaceLayout.legacy.cpp, GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSequencerUsageWithPaths.legacy.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.cpp, GenericInterfaceLayout.legacy.cpp, GigEVisionActionFeatures.cpp, Properties.cpp, Properties.legacy.cpp, SequenceCapture.win32.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, SingleCaptureStorage.cpp, TimestampFeatures.cpp, and exampleHelper.h.

Constructor & Destructor Documentation

FunctionInterface() [1/2]

FunctionInterface ( Device * pDev, RequestFactory * pRequestFactory = 0 )

inlineexplicit

Constructs a new function interface for the device pointed to by pDev.

In order to work with the mvIMPACT::acquire::FunctionInterface object the device needs to be initialized, so if the mvIMPACT::acquire::Device object pointed to by pDev in the constructors parameter list hasn't been opened already the constructor will try to do that. Thus internally a call to mvIMPACT::acquire::Device::open might be preformed with all consequences following from this call.

See also

mvIMPACT::acquire::Device::open

Parameters

[in]	pDev	A pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]	pRequestFactory	A pointer to a request factory. By supplying a custom request factory the user can control the type of request objects that will be created by the function interface.

Since

1.12.56

FunctionInterface() [2/2]

FunctionInterface ( const FunctionInterface & src )

inline

Constructs a new mvIMPACT::acquire::FunctionInterface from an existing one.

Parameters

[in]

src

A constant reference to the mvIMPACT::acquire::FunctionInterface object, this object shall be created from

~FunctionInterface()

virtual ~FunctionInterface ( void )

inlinevirtual

Class destructor.

Member Function Documentation

acquisitionStart()

int acquisitionStart ( void ) const

inline

Manually starts the acquisition engine of this device driver instance.

Calling this function will manually start this device driver's acquisition engine. This will only have an effect on the overall behaviour if mvIMPACT::acquire::Device::acquisitionStartStopBehaviour is set to mvIMPACT::acquire::assbUser.

If supported by the device driver, starting and stopping the acquisition engine manually can sometimes help to overcome capture queue underruns or certain restrictions in the underlying device driver technology.

See also

mvIMPACT::acquire::FunctionInterface::acquisitionStop,
mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure

Since

1.12.11

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• mvIMPACT::acquire::DMR_FEATURE_NOT_AVAILABLE if this device/driver combination does not support manual control over the acquisition engine. This will also happen if mvIMPACT::acquire::Device::acquisitionStartStopBehaviour is NOT set to mvIMPACT::acquire::assbUser.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Examples

GigEVisionActionFeatures.cpp, and exampleHelper.h.

acquisitionStop()

int acquisitionStop ( void ) const

inline

Manually stops the acquisition engine of this device driver instance.

Calling this function will manually stop this device drivers acquisition engine. This will only have effect on the overall behaviour, if mvIMPACT::acquire::Device::acquisitionStartStopBehaviour is set to mvIMPACT::acquire::assbUser.

See also

mvIMPACT::acquire::FunctionInterface::acquisitionStart,
mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure

Since

1.12.11

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• mvIMPACT::acquire::DMR_FEATURE_NOT_AVAILABLE if this device/driver combination does not support manual control over the acquisition engine. This will also happen if mvIMPACT::acquire::Device::acquisitionStartStopBehaviour is NOT set to mvIMPACT::acquire::assbUser.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Examples

exampleHelper.h.

createImageRequestControl()

int createImageRequestControl ( const std::string & name, const std::string & parent = "Base", ComponentList * pNewRequestControl = 0 )

inline

Creates a new mvIMPACT::acquire::ImageRequestControl object.

This function creates a new mvIMPACT::acquire::ImageRequestControl based on an existing one. New mvIMPACT::acquire::ImageRequestControl instances can only be derived from mvIMPACT::acquire::ImageRequestControl instances that already exist. When the driver has been initialized there will be at least one base mvIMPACT::acquire::ImageRequestControl called 'Base', which acts as the base for all other request controls.

All mvIMPACT::acquire::ImageRequestControl constructed by the application must be derived either from this base or any of its children using this function.

When this function succeeds, the mvIMPACT::acquire::ImageRequestControl constructor can be called with the name parameter passed to this function to get access to this newly registered mvIMPACT::acquire::ImageRequestControl.

Note

See all comments made under mvIMPACT::acquire::FunctionInterface::createSetting for understanding the relationship between base and derived mvIMPACT::acquire::ImageRequestControl objects.

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]	name	The name of the new mvIMPACT::acquire::ImageRequestControl object.
[in]	parent	The name of the mvIMPACT::acquire::ImageRequestControl the new object shall be derived from.
[out]	pNewRequestControl	A pointer to a mvIMPACT::acquire::ComponentList object that will receive the ID of the newly created request control. This parameter can be 0 if the application is not interested in that parameter.

createSetting()

int createSetting ( const std::string & name, const std::string & parent = "Base", ComponentList * pNewSetting = 0 )

inline

Creates a new setting.

This function creates a new setting base on an existing one. New settings can only be derived from settings that already exist. When the driver has been initialized there will be at least one base setting called 'Base', which acts as the base for all other settings.

When a new setting is created it derives all the properties from the parent setting. That means initially the new setting will contain the very same data as the parent setting. As long as a component hasn't been modified in the new setting it will depend on the parent settings data. That means if e.g. a property in the parent list is modified, the newly created setting will also benefit from the updated value.

To release a certain component from this dependency it must be assigned a new value. The function mvIMPACT::acquire::Component::isDefault will return false afterwards indicating that the component no longer depends on the parent.

To restore this parent <-> child dependency the user can call the function mvIMPACT::acquire::Component::restoreDefault. Afterwards settings applied to the parent component will also be visible in the child component again.

When a new setting has been created successfully the name used to create the setting can be passed to any of the constructors of the setting related classes (mvIMPACT::acquire::CameraSettingsBase, mvIMPACT::acquire::ImageProcessing, ...) to access the new components.

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]	name	The name of the setting to be created.
[in]	parent	The name of the setting to derive the new setting from.
[out]	pNewSetting	A pointer to a mvIMPACT::acquire::ComponentList object that will receive the ID of the newly created setting. This parameter can be 0 if the application is not interested in that parameter.

deleteSetting()

int deleteSetting ( const std::string & name, TStorageLocation storageLocation = slNative, TScope scope = sGlobal ) const

inline

Deletes a setting from the specified location.

This function deletes a setting from the specified location.

Since

2.19.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if the setting is available.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]	name	The name or the full path under where the setting is located.
[in]	storageLocation	The location of the setting.
[in]	scope	Specifies the scope of this operation.

deleteSettingFromStack()

int deleteSettingFromStack ( void )

inline

Deletes the last setting from the setting stack.

This function deletes the last setting from the setting stack.

See mvIMPACT::acquire::FunctionInterface::saveCurrentSettingOnStack for an example how to use this feature.

See also

mvIMPACT::acquire::FunctionInterface::saveCurrentSettingOnStack
mvIMPACT::acquire::FunctionInterface::loadSettingFromStack
mvIMPACT::acquire::FunctionInterface::loadAndDeleteSettingFromStack

Since

2.19.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if the setting is available.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

getAvailableImageRequestControls()

const std::vector< std::string > & getAvailableImageRequestControls ( void ) const

inline

Returns the names of the image request controls available for this mvIMPACT::acquire::Device.

This function returns a const reference to a string array containing the names of all image request controls available for the current mvIMPACT::acquire::Device. These names are valid constructor parameters for objects of the type mvIMPACT::acquire::ImageRequestControl.

New image request controls can be created by calling mvIMPACT::acquire::FunctionInterface::createImageRequestControl.

Returns

A const reference to an array containing the names of all settings available.

getAvailableSettings()

const std::vector< std::string > & getAvailableSettings ( void ) const

inline

Returns the names of the settings available for this mvIMPACT::acquire::Device.

This function returns a const reference to a string array containing the names of all settings available for the current mvIMPACT::acquire::Device. These names are valid constructor parameters for objects like mvIMPACT::acquire::CameraSettingsBase, mvIMPACT::acquire::ImageProcessing, mvIMPACT::acquire::ImageDestination or classes derived from these types.

New settings can be created by calling mvIMPACT::acquire::FunctionInterface::createSetting

Returns

A const reference to an array containing the names of all request controls available.

getCurrentCaptureBufferLayout() [1/2]

int getCurrentCaptureBufferLayout ( ImageRequestControl & imageRequestControl, int & size, int & alignment ) const

inline

Returns information about the current capture buffer requirements.

When an application wants to provide capture buffers, this function will be needed in order to get information on how the capture buffers must be constructed.

To find out more about capturing to user memory please refer to the application CaptureToUserMemory.cpp

See also

mvIMPACT::acquire::Request::configure

Since

1.12.68

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]	imageRequestControl	A reference to the mvIMPACT::acquire::ImageRequestControl object containing the setting for which the current capture buffer layout shall be queried. The setting can be defined via the property mvIMPACT::acquire::ImageRequestControl::setting.
[out]	size	On a successful call this variable will receive the size needed for capturing into user supplied buffers that use the current settings.
[out]	alignment	On a successful call this variable will receive the alignment needed for capturing into user supplied buffers that use the current settings.

getCurrentCaptureBufferLayout() [2/2]

int getCurrentCaptureBufferLayout ( ImageRequestControl & imageRequestControl, Request ** ppRequest = 0, int * pAlignment = 0 ) const

inline

Returns information about the current capture buffer requirements.

When an application wants to provide capture buffers, this function will be needed in order to get information on how the capture buffers must be constructed. The most important parameters will probably be alignment and size, thus for most application calling the other overload of this function will probably be enough.

To find out more about capturing to user memory please refer to the application CaptureToUserMemory.cpp

See also

mvIMPACT::acquire::Request::configure

Since

1.12.68

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]	imageRequestControl	A reference to the mvIMPACT::acquire::ImageRequestControl object containing the setting for which the current capture buffer layout shall be queried. The setting can be defined via the property mvIMPACT::acquire::ImageRequestControl::setting.
[out]	ppRequest	On a successful call this variable will receive a pointer to a mvIMPACT::acquire::Request object reflecting the current capture buffer layout.
[out]	pAlignment	On a successful call this variable will receive the alignment needed for capturing into user supplied buffers that use the current settings.

Examples

ContinuousCaptureToAVIFile.cpp.

getRequest()

Request * getRequest ( int nr ) const

inline

Returns a pointer to the desired mvIMPACT::acquire::Request.

This function returns a pointer to the mvIMPACT::acquire::Request stored at nr in the internal array of requests. If nr refers to an invalid mvIMPACT::acquire::Request
(e.g. when nr is higher than the actual number of
available requests) an STL out_of_range exception will be thrown.

Returns

A pointer to a mvIMPACT::acquire::Request object.

Parameters

[in]

nr

The number of the request to return

Examples

CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCaptureToAVIFile.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

getSetting()

ComponentList getSetting ( const std::string & name ) const

inline

Returns a mvIMPACT::acquire::ComponentList object to a setting with a specified name.

This function returns a mvIMPACT::acquire::ComponentList object to a setting with a specified name or will raise an exception if no such setting exists.

Since

1.12.58

Returns

A mvIMPACT::acquire::ComponentList object to a setting with a specified name

Parameters

[in]

name

The name of the setting to locate

imageRequestConfigure()

int imageRequestConfigure ( const Request * pRequest ) const

inline

Sets a request into configuration mode.

Note

Another version of this function is available that might be nicer to use depending on personal preferences and use case: mvIMPACT::acquire::Request::configure.

In configuration mode certain properties like mvIMPACT::acquire::Request::imageData, mvIMPACT::acquire::Request::imageSize, mvIMPACT::acquire::Request::imageMemoryMode of a request object can be modified. This can be used to configure one or more requests to use a user supplied memory. To use only a subset of the mvIMPACT::acquire::Request objects available the mvIMPACT::acquire::ImageRequestControl::requestToUse feature can be used.

Only requests that are currently not used by the driver and are not locked because they contain image data that hasn't been processed can be set into configuration mode.

Note

Instead of calling this function directly for most cases it is much more convenient to use the functions mvIMPACT::acquire::Request::attachUserBuffer and mvIMPACT::acquire::Request::detachUserBuffer instead.

User supplied buffers must follow the alignment and size requirements reported by versions of the function mvIMPACT::acquire::FunctionInterface::getCurrentCaptureBufferLayout. Calling a version of this function will return all the information required to allocate buffers that can be used to capture data for the specified settings.

When allocating memory on the heap, the complete buffer size is needed which is calculated like this:

size + alignment

Note

The address passed to the request object must be aligned already!

Device* pDev = getDevicePointerFromSomewhere()
FunctionInterface fi( pDev );
ImageRequestControl irc( pDev );
int bufferSize = 0;
int bufferAlignment = 0;
const TDMR_ERROR result = static_cast<TDMR_ERROR>( fi.getCurrentCaptureBufferLayout( irc, bufferSize, bufferAlignment ) );
Request* pRequest = fi.getRequest( 0 );
// the buffer assigned to the request object must be aligned accordingly
// the size of the user supplied buffer MUST NOT include the additional size
// caused by the alignment
if( pRequest->attachUserBuffer( getAlignedMemoryPtr( bufferSize, bufferAlignment ), bufferSize ) == DMR_NO_ERROR )
{
  irc.requestToUse.write( 0 ); // use the buffer just configured for the next image request
  // now the next image will be captured into the user supplied memory
  fi.imageRequestSingle( &irc ); // this will send request '0' to the driver
  // wait for the buffer. Once it has been returned by the driver AND the user buffer shall no
  // longer be used call
  if( pRequest->detachUserBuffer() != DMR_NO_ERROR )
  {
    // handle error
  }
  // now this request will use internal memory again.
}
else
{
   // handle error
}

Note

A request that is in configuration mode can't be sent to the driver for acquisition until mvIMPACT::acquire::Request::unlock or mvIMPACT::acquire::FunctionInterface::imageRequestUnlock has been called again. By using mvIMPACT::acquire::Request::attachUserBuffer and mvIMPACT::acquire::Request::detachUserBuffer this locking and unlocking is done internally thus the application does not need to worry about this.

See also

mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::Request::attachUserBuffer,
mvIMPACT::acquire::Request::detachUserBuffer,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::FunctionInterface::imageRequestReset

Since

1.10.31

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]

pRequest

A const pointer to the request object to configure

imageRequestReset()

int imageRequestReset ( int requestCtrlNr, int mode ) const

inline

Deletes all requests currently queued for the specified mvIMPACT::acquire::ImageRequestControl.

This function will terminate all running image acquisitions associated with the queue bound to the specified image request control and in addition to that will empty the queue of pending image requests for that queue. Also all requests that reside in the result queue and have not been picked up by the application will be unlocked and removed from the result queue. So after this function returns only the requests currently in possession of the application (so requests that have been picked up by successful calls to mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor that have NOT been unlocked) need to be handled. All other requests are in a state where they can be queued for an acquisition again.

See also

mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]	requestCtrlNr	The mvIMPACT::acquire::ImageRequestControl for which all the requests shall be cancelled.
[in]	mode	Currently unsupported. MUST be set 0.

Examples

ContinuousCapture.linux.cpp, ContinuousCaptureToAVIFile.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

imageRequestResultQueueElementCount()

int imageRequestResultQueueElementCount ( int queueNr = 0 ) const

inline

Returns the number of mvIMPACT::acquire::Request objects in the result queue .

This functions queries the number of mvIMPACT::acquire::Request objects currently in the result queue that are available for pickup. This number reflects the number of mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor calls that could be executed afterwards the would return with a valid mvIMPACT::acquire::Request object immediately without waiting!

See also

mvIMPACT::acquire::FunctionInterface::acquisitionStart,
mvIMPACT::acquire::FunctionInterface::acquisitionStop,
mvIMPACT::acquire::FunctionInterface::imageRequestReset,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestResultQueueElementCount,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure

Since

2.9.0

Returns

• The number of mvIMPACT::acquire::Request objects in the result queue if successful.
• mvIMPACT::acquire::DMR_INVALID_QUEUE_SELECTION if the selected result queue does not exist.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]

queueNr

The result queue to be queried.

imageRequestSingle()

int imageRequestSingle ( ImageRequestControl * pImageRequestControl = 0, int * pRequestUsed = 0 ) const

inline

Sends an image request to the mvIMPACT::acquire::Device driver.

This functions sends a single image request to the capture device. To wait for the image to become ready call the function mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor.

Attention

In order to make sure that no image data is lost, it is important to understand how the request mechanism works. The driver works with a fixed number of mvIMPACT::acquire::Request objects. The number of mvIMPACT::acquire::Request objects available to the driver can be set by modifying the property mvIMPACT::acquire::SystemSettings::requestCount. Each mvIMPACT::acquire::Request will consume a certain amount of memory. Once an image has been captured by the mvIMPACT::acquire::Request, this amount will be slightly more than the image itself needs in memory, so modify this parameter gently. On the other hand, it's necessary to have more than a single request in order to ensure a lossless acquisition. E.g. when working with free running cameras an image might be lost because while an image has been captured and is being processed, the next vertical sync. pulse is already missed before the mvIMPACT::acquire::Request is unlocked again.

Note

When mvIMPACT::acquire::Device::acquisitionStartStopBehaviour is set to mvIMPACT::acquire::assbUser several calls to mvIMPACT::acquire::FunctionInterface::imageRequestSingle will NOT start the data acquisition! After requests have been sent down to the driver, mvIMPACT::acquire::FunctionInterface::acquisitionStart must be called. For performance reasons some device drivers will NOT allow to request data into buffers which have not been known to the driver when mvIMPACT::acquire::FunctionInterface::acquisitionStart was called, thus before starting the acquisition, mvIMPACT::acquire::FunctionInterface::imageRequestSingle should be called as many times as there are request objects.

See also

mvIMPACT::acquire::FunctionInterface::acquisitionStart,
mvIMPACT::acquire::FunctionInterface::acquisitionStop,
mvIMPACT::acquire::FunctionInterface::imageRequestReset,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestResultQueueElementCount,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• mvIMPACT::acquire::DEV_NO_FREE_REQUEST_AVAILABLE if all mvIMPACT::acquire::Request objects are currently in use (either owned by the user or queued for acquisition).
• mvIMPACT::acquire::DEV_INVALID_REQUEST_NUMBER if the request number defined by the property ImageRequestControl::requestToUse is invalid (out of bounds).
• mvIMPACT::acquire::DEV_REQUEST_ALREADY_IN_USE if the request number defined by the property ImageRequestControl::requestToUse is already in use (either owned by the user or queued for acquisition).
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]	pImageRequestControl	A pointer to the mvIMPACT::acquire::ImageRequestControl object to be used for this request. mvIMPACT::acquire::ImageRequestControl objects define (among other things), which setting will be used for this image acquisition (via the property mvIMPACT::acquire::ImageRequestControl::setting). If this pointer is 0 the default request control will be used for this operation.
[out]	pRequestUsed	If a valid pointer to an integer is passed here, this variable receives the number of the mvIMPACT::acquire::Request which will be used to process this request.

Examples

ContinuousCapture.linux.cpp, ContinuousCaptureToAVIFile.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.legacy.cpp, GigEVisionActionFeatures.cpp, Properties.legacy.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

imageRequestUnlock()

int imageRequestUnlock ( int nr ) const

inline

Unlocks the request for the driver again.

Note

Another version of this function is available that might be nicer to use depending on personal preferences and use case: mvIMPACT::acquire::Request::unlock. Unlocking a certain request might be nicer by using this function, e.g. unlocking ALL requests in a loop is probably easier done by writing

Device* pDev = getDevicePointerFromSomewhere()
FunctionInterface fi( pDev );
const int rc = static_cast< int >( fi.requestCount() );
for( int i=0; i<rc; i++ )
{
  fi.imageRequestUnlock( i );
}

To ensure that no image data is overwritten by another image request while the user still deals with the image from a previous acquisition each image buffer will be locked by the driver when it is returned to the user by a call to mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor. No new image will be captured into the same buffer until the user unlocks the buffer again by calling mvIMPACT::acquire::FunctionInterface::imageRequestUnlock.

Note

After unlocking a request it is no longer guaranteed that the memory once referenced by the request and the image buffer belonging to it stays valid, so do NEVER try to access memory belonging to an unlocked request object. If you need to copy the image buffer or modify it in any other way, do everything you have to do BEFORE calling this function!

See also

mvIMPACT::acquire::FunctionInterface::imageRequestReset,
mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::FunctionInterface::imageRequestResultQueueElementCount,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• mvIMPACT::acquire::DEV_REQUEST_CANT_BE_UNLOCKED if the request number defined by nr is currently not owned by the application (either already unlocked or queued for acquisition).
• mvIMPACT::acquire::DMR_INPUT_BUFFER_TOO_SMALL if the request number defined by nr has been configured to capture into a user supplied buffer but the buffer is too small to acquire data into.
• mvIMPACT::acquire::DEV_REQUEST_BUFFER_MISALIGNED if the request number defined by nr has been configured to capture into a user supplied buffer but this buffer is not aligned in order to the alignment restrictions reported by this driver/device combination.
• mvIMPACT::acquire::DEV_REQUEST_BUFFER_INVALID if the request number defined by nr has been configured to capture into a user supplied buffer but an invalid (NULL) pointer has been attached to the request.
• mvIMPACT::acquire::DEV_INVALID_REQUEST_NUMBER if the request number defined by nr is invalid (out of bounds).
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]

nr

The number of the request to unlock. This is typically a value returned from a call to mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor.

Examples

ContinuousCaptureToAVIFile.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

imageRequestWaitFor()

int imageRequestWaitFor ( int timeout_ms, int queueNr = 0 ) const

inline

Waits for a request object to become ready.

This function waits for a request object previously sent to the capture device by calling mvIMPACT::acquire::FunctionInterface::imageRequestSingle. When a new request became ready during the period of time specified by the timeout_ms parameter this request is extracted from the result queue and is returned to the user so the same request can not be returned twice until it has been processed and unlocked by the application.

Note

Whenever a mvIMPACT::acquire::Request is returned to the user the image data described by the mvIMPACT::acquire::Request remains valid until the user unlocks the image buffer again or the driver is closed.

See also

mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestResultQueueElementCount,
mvIMPACT::acquire::FunctionInterface::getRequest

Returns

If the return value is greater than or equal to zero, the return value is the request number of the image request in the interface's internal array of image requests. In this case the user can call mvIMPACT::acquire::FunctionInterface::getRequest to get access to the results.

If the result is negative, the return value is an error code. The error code that is returned in most cases will be mvIMPACT::acquire::DEV_WAIT_FOR_REQUEST_FAILED. To find out possible reasons for this error, look at the corresponding explanation.

Parameters

[in]	timeout_ms	The maximum wait time in milliseconds (ms) for this request to become ready. If timeout_ms is '-1', the function's timeout interval never elapses. If the result queue specified by the queueNr parameter already contains a request when calling this function the function will return immediately. Please note that each request has its own timeout that is independent from this wait timeout, thus this function will return with a valid request after the timeout for this request has elapsed even if e.g. a trigger has not been detected. For detailed information on the interaction of the timeout of this function and the timeout of a request please refer to the chapter Acquiring Data in the C++ section.
[in]	queueNr	The queue where to wait for the request. The number of request queues available depends on the number of video channels offered by the device. The queue a processed request ends up in can be defined by setting the property mvIMPACT::acquire::ImageRequestControl::resultQueue BEFORE calling mvIMPACT::acquire::FunctionInterface::imageRequestSingle.

Examples

ContinuousCapture.linux.cpp, ContinuousCaptureToAVIFile.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

isRequestNrValid()

bool isRequestNrValid ( int nr ) const

inline

Check if nr specifies a valid mvIMPACT::acquire::Request.

Returns

• true if nr specifies a valid request.
• false otherwise

Examples

ContinuousCapture.linux.cpp, ContinuousCaptureToAVIFile.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

isSettingAvailable()

int isSettingAvailable ( const std::string & name, TStorageLocation storageLocation = slNative, TScope scope = sGlobal ) const

inline

Checks if a certain setting is available under the specified location.

This function checks if a certain setting is available under the specified location.

Since

2.19.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if the setting is available.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]	name	The name or the full path under where the setting is located.
[in]	storageLocation	The location of the setting.
[in]	scope	Specifies the scope of this operation.

loadAndDeleteSettingFromStack()

int loadAndDeleteSettingFromStack ( void )

inline

loads the last setting from the setting stack and then removes this setting from the stack.

This function loads the last setting from the setting stack and then removes this setting from the stack.

See mvIMPACT::acquire::FunctionInterface::saveCurrentSettingOnStack for an example how to use this feature.

See also mvIMPACT::acquire::FunctionInterface::loadSetting to find out which features of a GenICam device are stored in a setting and which are not!

See also

mvIMPACT::acquire::FunctionInterface::saveCurrentSettingOnStack
mvIMPACT::acquire::FunctionInterface::deleteSettingFromStack
mvIMPACT::acquire::FunctionInterface::loadSettingFromStack

Since

2.19.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if the setting is available.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

loadSetting()

int loadSetting ( const std::string & name, TStorageFlag storageFlags = sfNative, TScope scope = sGlobal ) const

inline

Loads a previously stored setting.

This function can be used to restore a previously stored setting again.

To load a setting from a file the mvIMPACT::acquire::sfFile should be specified as part of storageFlags. To load a setting from a platform specific location such as the Registry under Windows© mvIMPACT::acquire::sfNative should be specified. It's not allowed to combine mvIMPACT::acquire::sfFile and mvIMPACT::acquire::sfNative for this operation.

Attention

Since Impact Acquire 2.9.0 GenICam devices will be able to save their properties in an XML File, only if the properties have the streamable attribute set (for more information refer to the GenICam standard specification). Properties with no streamable attribute set, will be silently ignored when saving, which means they will not be saved in the XML file. For Balluff GenICam devices, starting with firmware version 1.6.414 the streamable attribute is set for all the necessary properties.

Attention

Since Impact Acquire 2.9.0 and again in version 2.11.0 storing and loading of camera settings in an XML file for the mvIMPACT::acquire::dilGenICam interface layout has been updated. As a result XML files created with newer versions of Impact Acquire might not be readable on systems with older version of Impact Acquire installed. XML files created on systems with earlier versions of Impact Acquire will always be readable this or newer versions. See the following table for details.

Impact Acquire Version	Loading an XML settings file created with Impact Acquire version < 2.9.0	Loading an XML settings file created with Impact Acquire version 2.9.0 - 2.10.1	Loading an XML settings file created with Impact Acquire version 2.11.0 or later
< 2.9.0	YES	NO	NO
2.9.0 - 2.10.1	YES	YES	NO
>= 2.11.0	YES	YES	YES

Since Impact Acquire 2.28.0 it is possible for devices operated in the dilGenICam interface layout to store settings including sequencer sets and user sets (see SFNC for details) data by specifying the sfProcessGenICamSequencerData and/or sfProcessGenICamUserSetData during the storage operation. Settings stored like this cannot be loaded by previous Impact Acquire versions.

Note

For devices operated in the mvIMPACT::acquire::dilGenICam interface layout further restriction apply: Settings created with a certain product type can only be used with other devices belonging to the exact same type as defined by the property mvIMPACT::acquire::Device::product inside the device list (the one device specific property list that is accessible without initialising the device before). Even if a setting can be used with various firmware versions it is recommended to use one setting for multiple devices all updated to the very same firmware version to avoid compatibility problems.

See also

mvIMPACT::acquire::FunctionInterface::saveSetting.

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]	name	The name or the full path under where the setting is located.
[in]	storageFlags	The flags which define which information shall be read from the location and how this information shall be interpreted.
[in]	scope	Specifies where the information is located.

Examples

ContinuousCapture.linux.cpp, and Properties.legacy.cpp.

loadSettingFromDefault()

int loadSettingFromDefault ( TScope scope = sUser ) const

inline

Loads the default settings.

This function will try to load the settings from a default location. This function can only succeed if a setting has been stored previously by a call to mvIMPACT::acquire::FunctionInterface::saveSettingToDefault.

Attention

There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of Impact Acquire as well as in version 2.28.0. See mvIMPACT::acquire::FunctionInterface::loadSetting for details.

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]

scope

Specifies where the information is located.

loadSettingFromStack()

int loadSettingFromStack ( void )

inline

loads the last setting from the setting stack.

This function loads the last setting from the setting stack.

See mvIMPACT::acquire::FunctionInterface::saveCurrentSettingOnStack for an example how to use this feature.

See also mvIMPACT::acquire::FunctionInterface::loadSetting to find out which features of a GenICam device are stored in a setting and which are not!

See also

mvIMPACT::acquire::FunctionInterface::saveCurrentSettingOnStack
mvIMPACT::acquire::FunctionInterface::deleteSettingFromStack
mvIMPACT::acquire::FunctionInterface::loadAndDeleteSettingFromStack

Since

2.19.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if the setting is available.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

operator=()

FunctionInterface & operator= ( const FunctionInterface & rhs )

inline

Allows assignments of mvIMPACT::acquire::FunctionInterface objects.

requestCount()

unsigned int requestCount ( void ) const

inline

Returns the number of available request objects.

See also

mvIMPACT::acquire::SystemSettings::requestCount to change the number of request objects

Returns

Returns the number of available request objects.

Examples

CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, and CaptureToUserMemory.legacy.cpp.

saveCurrentSettingOnStack()

int saveCurrentSettingOnStack ( TStorageFlag storageFlags = sfRAM )

inline

Saves the current setting on the setting stack.

This function saves the current setting on the setting stack. Together which the functions mentioned below this implements a stack for capture settings. This can become handy when entering a section of code that might modify the current capture settings in various ways and depending on the result these modifications shall either be kept or discarded at the end of the operation.

// ...
enum TResult
{
  rApply,
  rDiscard
};
// ...
FunctionInterface& fi = getFunctionInterfaceFromSomewhere();
fi.saveCurrentSettingOnStack();
switch( enterSectionThatModifiesDeviceSettings() )
{
case rDiscard:
    fi.loadAndDeleteSettingFromStack(); // revert all changes just applied without worrying about what these changes actually are
    break;
case rApply:
    fi.deleteSettingFromStack(); // remove the setting from the stack, but keep changes
    break;
}

The stack makes use of Impact Acquires ability to store capture settings in the memory of the current process. Once the last instance of this mvIMPACT::acquire::FunctionInterface object is deleted all settings pushed on this stack will be deleted automatically.

See also

mvIMPACT::acquire::FunctionInterface::deleteSettingFromStack
mvIMPACT::acquire::FunctionInterface::loadSettingFromStack
mvIMPACT::acquire::FunctionInterface::loadAndDeleteSettingFromStack

Since

2.19.0

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if the setting is available.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]

storageFlags

The flags which define which information shall be stored and how this information shall be stored.

saveSetting()

int saveSetting ( const std::string & name, TStorageFlag storageFlags = sfNative, TScope scope = sGlobal ) const

inline

Stores the current settings.

This function can be used to store the current settings either in an XML-file or (under Windows©) into the Registry. A setting contains all the values set for properties that control the overall way an image is acquired( e.g. the exposure time, etc.).

To store a setting in a file the mvIMPACT::acquire::sfFile should be specified as part of storageFlags. To store a setting in a platform specific location such as the Registry under Windows© mvIMPACT::acquire::sfNative should be specified. Both flags can be combined. In that case the same setting will be stored in a file AND in a platform specific location if these location differ (platform dependent!).

Attention

There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of Impact Acquire as well as in version 2.28.0. See mvIMPACT::acquire::FunctionInterface::loadSetting for details.

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]	name	The name or the full path under which this setting shall be stored
[in]	storageFlags	The flags which define which information shall be stored and how this information shall be stored.
[in]	scope	Specifies where the information shall be stored.

Examples

Properties.legacy.cpp.

saveSettingToDefault()

int saveSettingToDefault ( TScope scope = sUser ) const

inline

Stores the current settings under a default location.

Under Windows© this will be in the Registry. A setting contains all the values set for properties that control the overall way an image is acquired( e.g. the exposure time, etc.).

Attention

There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of Impact Acquire as well as in version 2.28.0. See mvIMPACT::acquire::FunctionInterface::loadSetting for details.

Returns

• mvIMPACT::acquire::DMR_NO_ERROR if successful.
• A negative error code of type mvIMPACT::acquire::TDMR_ERROR or mvIMPACT::acquire::TPROPHANDLING_ERROR otherwise.

Parameters

[in]

scope

Specifies where the information shall be stored.

updateRequests()

void updateRequests ( void ) const

inline

Updates the internal cache for request objects.

Calling this function isn't strictly necessary but doing so can speed up the initial execution of other functions after the request count has been modified using the mvIMPACT::acquire::SystemSettings::requestCount property. Not doing so will execute the work performed by this function when calling any of the following functions for the first time after modifying the request count:

• mvIMPACT::acquire::FunctionInterface::getRequest
• mvIMPACT::acquire::FunctionInterface::isRequestNrValid
• mvIMPACT::acquire::FunctionInterface::requestCount

See also

mvIMPACT::acquire::SystemSettings::requestCount

Examples

GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSequencerUsageWithPaths.cpp, and GenICamSequencerUsageWithPaths.legacy.cpp.