mvIMPACT Acquire SDK C++
FunctionInterface Class Reference

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

Public Member Functions

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

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.

EXAMPLE

This sample assumes a valid pointer to a mvIMPACT::acquire::Device object has been obtained. To find out how to do that see the detailed description of the class mvIMPACT::acquire::DeviceManager.

using namespace std;
using namespace mvIMPACT::acquire;
static volatile bool s_boTerminated = false;
//-----------------------------------------------------------------------------
void showPropVal( const Property& prop )
//-----------------------------------------------------------------------------
{
cout << prop.name() << ": " << prop.readS() << endl;
}
//-----------------------------------------------------------------------------
void captureThread( Device* pDev )
//-----------------------------------------------------------------------------
{
if( !pDev )
{
return; // error! Invalid pointer!
}
SettingsBlueFOX setting(pDev);
int maxExposureTime = setting.cameraSetting.expose_us.read( Property::maxValue );
// make sure enough requests are available:
SystemSettings ss(pDev);
const int REQUEST_COUNT = ss.requestCount.read();
// pre-fill the default capture queue
for( unsigned int i=0; i<REQUEST_COUNT; i++ )
{
int result = fi.imageRequestSingle();
if( result != DMR_NO_ERROR )
{
cout << "Error while filling the request queue: " << ImpactAcquireException::getErrorCodeAsString( result ) << endl;
}
}
// run thread loop
const Request* pRequest = 0;
int requestNr = INVALID_ID;
while( !s_boTerminated )
{
// wait for results from the default capture queue
requestNr = fi.imageRequestWaitFor( 500 );
if( fi.isRequestNrValid( requestNr ) )
{
pRequest = fi.getRequest( requestNr );
if( pRequest->isOK() )
{
++cnt;
if( cnt%100 == 0 )
{
// modify the exposure time to see how modifying
// properties affects the capture results
setting.cameraSetting.expose_us.write( ( cnt * 100 ) % maxExposureTime );
// display some statistics
showPropVal( setting.cameraSetting.expose_us );
showPropVal( statistics.framesPerSecond );
showPropVal( statistics.captureTime_s );
}
// do whatever is necessary to display/store or process the image
}
else
{
cout << "Error: " << pRequest->getParamS( irpResult ) << endl;
}
fi.imageRequestUnlock( requestNr );
fi.imageRequestSingle();
}
else
{
// If the error code is -2119(DEV_WAIT_FOR_REQUEST_FAILED), the documentation will provide
// additional information under TDMR_ERROR in the interface reference
cout << "imageRequestWaitFor failed (" << requestNr << ")"
<< ", timeout value too small?" << endl;
}
}
// free resources
fi.imageRequestReset( 0, 0 );
}
Examples
CaptureToUserMemory.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureMultipleVideoSignals.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureToAVIFile.cpp, exampleHelper.h, GenericInterfaceLayout.cpp, GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSmartFrameRecallUsage.cpp, LiveSnap.cpp, Properties.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureStorage.cpp.

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
Device::open
Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]pRequestFactoryA 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]srcA 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
Examples
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
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 at least be 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
Parameters
[in]nameThe name of the new mvIMPACT::acquire::ImageRequestControl object.
[in]parentThe name of the mvIMPACT::acquire::ImageRequestControl the new object shall be derived from.
[out]pNewRequestControlA 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 at least be 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
Parameters
[in]nameThe name of the setting to be created.
[in]parentThe name of the setting to derive the new setting from.
[out]pNewSettingA 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.
Examples
ContinuousCaptureMultipleVideoSignals.cpp.

◆ 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
Parameters
[in]nameThe name or the full path under where the setting is located.
[in]storageLocationThe location of the setting.
[in]scopeSpecifies 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

◆ 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,
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
Parameters
[in]imageRequestControlA 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]ppRequestOn a successful call this variable will receive a pointer to a mvIMPACT::acquire::Request object reflecting the current capture buffer layout.
[out]pAlignmentOn a successful call this variable will receive the alignment needed for capturing into user supplied buffers that use the current settings.
Examples
ContinuousCaptureToAVIFile.cpp.

◆ getCurrentCaptureBufferLayout() [2/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
Parameters
[in]imageRequestControlA 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]sizeOn a successful call this variable will receive the size needed for capturing into user supplied buffers that use the current settings.
[out]alignmentOn a successful call this variable will receive the alignment needed for capturing into user supplied buffers that use the current settings.

◆ 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) a STL out_of_range exception will be thrown.

Returns
A pointer to a mvIMPACT::acquire::Request object.
Parameters
[in]nrThe number of the request to return
Examples
CaptureToUserMemory.cpp, ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureToAVIFile.cpp, LiveSnap.cpp, SingleCapture.cpp, and SingleCaptureMasterSlave.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]nameThe 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()
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(), getAlignedMemorySize() ) ) == DMR_NO_ERROR )
{
ImageRequestControl irc(pDev);
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
Parameters
[in]pRequestA 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
Parameters
[in]requestCtrlNrThe mvIMPACT::acquire::ImageRequestControl for which all the requests shall be cancelled.
[in]modeCurrently unsupported. MUST be set 0.
Examples
ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureToAVIFile.cpp, LiveSnap.cpp, and SingleCaptureMasterSlave.cpp.

◆ imageRequestResultQueueElementCount()

int imageRequestResultQueueElementCount ( int  queueNr = 0) const
inline

◆ 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 send 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
Parameters
[in]pImageRequestControlA 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).
[out]pRequestUsedIf 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
ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureToAVIFile.cpp, GenICamSmartFrameRecallUsage.cpp, LiveSnap.cpp, SingleCapture.cpp, and SingleCaptureMasterSlave.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()
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
Parameters
[in]nrThe number of the request to unlock. This is typically a value returned from a call to mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor.
Examples
ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureToAVIFile.cpp, LiveSnap.cpp, SingleCapture.cpp, and SingleCaptureMasterSlave.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 positive, 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_msThe 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]queueNrThe 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
ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureToAVIFile.cpp, LiveSnap.cpp, SingleCapture.cpp, and SingleCaptureMasterSlave.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
ContinuousCaptureMultipleInputs.cpp, ContinuousCaptureToAVIFile.cpp, LiveSnap.cpp, SingleCapture.cpp, and SingleCaptureMasterSlave.cpp.

◆ isRequestOK()

bool isRequestOK ( const Request p) const

Checks if a request has been processed successfully(deprecated).

Deprecated:
This function has been declared deprecated and will be removed in future versions of this interface. Use mvIMPACT::acquire::Request::isOK() instead and see the corresponding 'Porting existing code' section in the documentation.
Returns
  • true if the request has been processed successfully.
  • false otherwise.[in] The request to check

◆ 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
Parameters
[in]nameThe name or the full path under where the setting is located.
[in]storageLocationThe location of the setting.
[in]scopeSpecifies 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

◆ 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.

Warning
Since mvIMPACT Acquire 2.9.0 GenICam devices will be able to save their properties in a 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 MATRIX VISION GenICam cameras, starting with firmware version 1.6.414 the streamable attribute is set for all the necessary properties.


Warning
Since mvIMPACT Acquire 2.9.0 and again in version 2.11.0 storing and loading of camera settings in a XML file for the mvIMPACT::acquire::dilGenICam interface layout has been updated. As a result XML files created with newer versions of mvIMPACT Acquire might not be readable on systems with older version of mvIMPACT Acquire installed. XML files created on systems with earlier versions of mvIMPACT Acquire will always be readable this or newer versions. See the following table for details.
mvIMPACT Acquire VersionLoading a XML settings file created with mvIMPACT Acquire version < 2.9.0Loading a XML settings file created with mvIMPACT Acquire version 2.9.0 - 2.10.1Loading a XML settings file created with mvIMPACT 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
Attention
Since mvIMPACT Acquire 2.28.0 it is possible for devices operated in the dilGenICam interface layout to store settings including including sequencer set and user set (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 mvIMPACT 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
Parameters
[in]nameThe name or the full path under where the setting is located.
[in]storageFlagsThe flags which define which information shall be read from the location and how this information shall be interpreted.
[in]scopeSpecifies where the information is located.
Examples
LiveSnap.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.

Warning
There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of mvIMPACT Acquire as well as in version 2.28.0. See mvIMPACT::acquire::FunctionInterface::loadSetting for details.
Returns
Parameters
[in]scopeSpecifies 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

◆ 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
CaptureToUserMemory.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 mvIMPACT 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
Parameters
[in]storageFlagsThe 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 a 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!).

Warning
There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of mvIMPACT Acquire as well as in version 2.28.0. See mvIMPACT::acquire::FunctionInterface::loadSetting for details.
Returns
Parameters
[in]nameThe name or the full path under which this setting shall be stored
[in]storageFlagsThe flags which define which information shall be stored and how this information shall be stored.
[in]scopeSpecifies where the information shall be stored.

◆ 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.).

Warning
There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of mvIMPACT Acquire as well as in version 2.28.0. See mvIMPACT::acquire::FunctionInterface::loadSetting for details.
Returns
Parameters
[in]scopeSpecifies where the information shall be stored.

◆ saveSystemToDefault()

int saveSystemToDefault ( TScope  scope = sUser) const

Stores the current system settings under a default location (deprecated).

Deprecated:
Note
This function has been declared deprecated and will be removed in version 2.0.0 of this interface. All features that have been stored using this method will now also be handled by the functions that load and save settings. Please see the corresponding 'Porting existing code' section in the documentation.

These are the settings which can be altered by creating an instance of the class mvIMPACT::acquire::SystemSettings. Under Windows© this function will store the current settings in the Registry.

Modifying data in this section of properties will affect every device belonging to the same family (e.g. every USB 2.0 camera device) when the data is saved. When the modified data is stored it will be restored by each device belonging to the same family during the next initialisation. So at runtime changing and saving the settings of one device will not affect the behaviour of another until the data has been stored and the other device has been closed and reopened again.

Returns

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