Impact Acquire SDK Java
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
FunctionInterface Class Reference
Common

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

Public Member Functions

int acquisitionStart ()
 Manually starts the acquisition engine of this device driver instance.
 
int acquisitionStop ()
 Manually stops the acquisition engine of this device driver instance.
 
int createImageRequestControl (String name)
 Creates a new mvIMPACT.acquire.ImageRequestControl object.
 
int createImageRequestControl (String name, String parent)
 Creates a new mvIMPACT.acquire.ImageRequestControl object.
 
int createImageRequestControl (String name, String parent, ComponentList pNewRequestControl)
 Creates a new mvIMPACT.acquire.ImageRequestControl object.
 
int createSetting (String name)
 Creates a new setting.
 
int createSetting (String name, String parent)
 Creates a new setting.
 
int createSetting (String name, String parent, ComponentList pNewSetting)
 Creates a new setting.
 
synchronized void delete ()
 
int deleteSetting (String name)
 Deletes a setting from the specified location.
 
int deleteSetting (String name, int storageLocation)
 Deletes a setting from the specified location.
 
int deleteSetting (String name, int storageLocation, int scope)
 Deletes a setting from the specified location.
 
int deleteSettingFromStack ()
 Deletes the last setting from the setting stack.
 
 FunctionInterface (Device pDev)
 Constructs a new function interface for the device pointed to by pDev.
 
 FunctionInterface (Device pDev, RequestFactory pRequestFactory)
 Constructs a new function interface for the device pointed to by pDev.
 
 FunctionInterface (FunctionInterface src)
 Constructs a new mvIMPACT.acquire.FunctionInterface from an existing one.
 
StringVector getAvailableImageRequestControls ()
 Returns the names of the image request controls available for this mvIMPACT.acquire.Device.
 
StringVector getAvailableSettings ()
 Returns the names of the settings available for this mvIMPACT.acquire.Device.
 
Request getCurrentCaptureBufferLayout (ImageRequestControl imageRequestControl, int[] alignment)
 On a successful call a pointer to a mvIMPACT.acquire.Request object reflecting the current capture buffer layout will be returned.
 
int getCurrentCaptureBufferLayout (ImageRequestControl imageRequestControl, int[] size, int[] alignment)
 Returns information about the current capture buffer requirements.
 
Request getRequest (int nr)
 Returns a pointer to the desired mvIMPACT.acquire.Request.
 
ComponentList getSetting (String name)
 Returns a mvIMPACT.acquire.ComponentList object to a setting with a specified name.
 
int imageRequestConfigure (Request pRequest)
 Sets a request into configuration mode.
 
int imageRequestReset (int requestCtrlNr, int mode)
 Deletes all requests currently queued for the specified mvIMPACT.acquire.ImageRequestControl.
 
int imageRequestResultQueueElementCount ()
 Returns the number of mvIMPACT.acquire.Request objects in the result queue .
 
int imageRequestResultQueueElementCount (int queueNr)
 Returns the number of mvIMPACT.acquire.Request objects in the result queue .
 
int imageRequestSingle ()
 Sends an image request to the mvIMPACT.acquire.Device driver.
 
int imageRequestSingle (ImageRequestControl imageRequestControl)
 Sends an image request to the mvIMPACT.acquire.Device driver.
 
int imageRequestSingle (ImageRequestControl imageRequestControl, int[] requestUsed)
 Sends an image request to the mvIMPACT.acquire.Device driver.
 
int imageRequestUnlock (int nr)
 Unlocks the request for the driver again.
 
int imageRequestWaitFor (int timeout_ms)
 Waits for a request object to become ready.
 
int imageRequestWaitFor (int timeout_ms, int queueNr)
 Waits for a request object to become ready.
 
boolean isRequestNrValid (int nr)
 Check if nr specifies a valid mvIMPACT.acquire.Request.
 
int isSettingAvailable (String name)
 Checks if a certain setting is available under the specified location.
 
int isSettingAvailable (String name, int storageLocation)
 Checks if a certain setting is available under the specified location.
 
int isSettingAvailable (String name, int storageLocation, int scope)
 Checks if a certain setting is available under the specified location.
 
int loadAndDeleteSettingFromStack ()
 loads the last setting from the setting stack and then removes this setting from the stack.
 
int loadSetting (String name)
 Loads a previously stored setting.
 
int loadSetting (String name, int storageFlags)
 Loads a previously stored setting.
 
int loadSetting (String name, int storageFlags, int scope)
 Loads a previously stored setting.
 
int loadSettingFromDefault ()
 Loads the default settings.
 
int loadSettingFromDefault (int scope)
 Loads the default settings.
 
int loadSettingFromStack ()
 loads the last setting from the setting stack.
 
long requestCount ()
 Returns the number of available request objects.
 
int saveCurrentSettingOnStack ()
 Saves the current setting on the setting stack.
 
int saveCurrentSettingOnStack (int storageFlags)
 Saves the current setting on the setting stack.
 
int saveSetting (String name)
 Stores the current settings.
 
int saveSetting (String name, int storageFlags)
 Stores the current settings.
 
int saveSetting (String name, int storageFlags, int scope)
 Stores the current settings.
 
int saveSettingToDefault ()
 Stores the current settings under a default location.
 
int saveSettingToDefault (int scope)
 Stores the current settings under a default location.
 
void updateRequests ()
 Updates the internal cache for request objects.
 

Protected Member Functions

void finalize ()
 
 FunctionInterface (long cPtr, boolean cMemoryOwn)
 

Static Protected Member Functions

static long swigRelease (FunctionInterface obj)
 

Protected Attributes

transient boolean swigCMemOwn
 

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:

Constructor & Destructor Documentation

◆ FunctionInterface() [1/4]

FunctionInterface ( long cPtr,
boolean cMemoryOwn )
protected

◆ FunctionInterface() [2/4]

FunctionInterface ( Device pDev,
RequestFactory pRequestFactory )

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
pDev[in] A pointer to a mvIMPACT.acquire.Device object obtained from a mvIMPACT.acquire.DeviceManager object.
pRequestFactory[in] 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() [3/4]

FunctionInterface ( Device pDev)

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
pDev[in] A pointer to a mvIMPACT.acquire.Device object obtained from a mvIMPACT.acquire.DeviceManager object. 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() [4/4]

FunctionInterface ( FunctionInterface src)

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

Parameters
src[in] A constant reference to the mvIMPACT.acquire.FunctionInterface object, this object shall be created from

Member Function Documentation

◆ acquisitionStart()

int acquisitionStart ( )

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.getAcquisitionStartStopBehaviour() is set to mvIMPACT.acquire.TAcquisitionStartStopBehaviour.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

◆ acquisitionStop()

int acquisitionStop ( )

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.getAcquisitionStartStopBehaviour() is set to mvIMPACT.acquire.TAcquisitionStartStopBehaviour.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

◆ createImageRequestControl() [1/3]

int createImageRequestControl ( String name)

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
Parameters
name[in] The name of the new mvIMPACT.acquire.ImageRequestControl object. This parameter can be 0 if the application is not interested in that parameter.

◆ createImageRequestControl() [2/3]

int createImageRequestControl ( String name,
String parent )

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
Parameters
name[in] The name of the new mvIMPACT.acquire.ImageRequestControl object.
parent[in] The name of the mvIMPACT.acquire.ImageRequestControl the new object shall be derived from. This parameter can be 0 if the application is not interested in that parameter.

◆ createImageRequestControl() [3/3]

int createImageRequestControl ( String name,
String parent,
ComponentList pNewRequestControl )

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
Parameters
name[in] The name of the new mvIMPACT.acquire.ImageRequestControl object.
parent[in] The name of the mvIMPACT.acquire.ImageRequestControl the new object shall be derived from.
pNewRequestControl[out] 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() [1/3]

int createSetting ( String name)

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
Parameters
name[in] The name of the setting to be created. This parameter can be 0 if the application is not interested in that parameter.

◆ createSetting() [2/3]

int createSetting ( String name,
String parent )

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
Parameters
name[in] The name of the setting to be created.
parent[in] The name of the setting to derive the new setting from. This parameter can be 0 if the application is not interested in that parameter.

◆ createSetting() [3/3]

int createSetting ( String name,
String parent,
ComponentList pNewSetting )

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
Parameters
name[in] The name of the setting to be created.
parent[in] The name of the setting to derive the new setting from.
pNewSetting[out] 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.

◆ delete()

synchronized void delete ( )

◆ deleteSetting() [1/3]

int deleteSetting ( String name)

Deletes a setting from the specified location.

This function deletes a setting from the specified location.

Since
2.19.0
Returns
Parameters
name[in] The name or the full path under where the setting is located.

◆ deleteSetting() [2/3]

int deleteSetting ( String name,
int storageLocation )

Deletes a setting from the specified location.

This function deletes a setting from the specified location.

Since
2.19.0
Returns
Parameters
name[in] The name or the full path under where the setting is located.
storageLocation[in] The location of the setting.

◆ deleteSetting() [3/3]

int deleteSetting ( String name,
int storageLocation,
int scope )

Deletes a setting from the specified location.

This function deletes a setting from the specified location.

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

◆ deleteSettingFromStack()

int deleteSettingFromStack ( )

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

◆ finalize()

void finalize ( )
protected

◆ getAvailableImageRequestControls()

StringVector getAvailableImageRequestControls ( )

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()

StringVector getAvailableSettings ( )

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]

Request getCurrentCaptureBufferLayout ( ImageRequestControl imageRequestControl,
int[] alignment )

On a successful call a pointer to a mvIMPACT.acquire.Request object reflecting the current capture buffer layout will be returned.

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.

See also
mvIMPACT.acquire.Request.configure
Since
2.36.0
Returns
  • A pointer to a mvIMPACT.acquire.Request object if successful.
  • NULL otherwise. In this case a driver update might be required. See other versions of this function returning an error code then to find out what is the actual problem!
Parameters
imageRequestControl[in] 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.getSetting().
alignment[out] 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,
int[] size,
int[] alignment )

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.

See also
mvIMPACT.acquire.Request.configure
Since
1.12.68
Returns
Parameters
imageRequestControl[in] 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.getSetting().
size[out] On a successful call this variable will receive the size needed for capturing into user supplied buffers that use the current settings.
alignment[out] On 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)

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.

Returns
A pointer to a mvIMPACT.acquire.Request object.
Parameters
nr[in] The number of the request to return

◆ getSetting()

ComponentList getSetting ( String name)

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
name[in] The name of the setting to locate

◆ imageRequestConfigure()

int imageRequestConfigure ( Request pRequest)

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.getImageData(), mvIMPACT.acquire.Request.getImageSize(), mvIMPACT.acquire.Request.getImageMemoryMode() 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.getRequestToUse() 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!
Attention
There is currently no way to deal with alignment in Java when capturing into user supplied(thus managed) memory! Suggestions welcome!
import java.nio.ByteBuffer;
// ...
Device pDev = getDevicePointerFromSomewhere()
FunctionInterface fi = new FunctionInterface( pDev );
ImageRequestControl irc = new ImageRequestControl( pDev );
int[] bufferSize = {0};
int[] bufferAlignment = {0};
if( fi.getCurrentCaptureBufferLayout( irc, bufferSize, bufferAlignment ) == TDMR_ERROR.DMR_NO_ERROR )
{
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
ByteBuffer pBuffer = ByteBuffer.allocateDirect( bufferSize[0] + bufferAlignment[0] ); // todo: There is currently no way to deal with alignment in Java! Suggestions welcome!
if( pRequest.attachUserBuffer( pBuffer ) == TDMR_ERROR.DMR_NO_ERROR )
{
irc.getRequestToUse().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() != TDMR_ERROR.DMR_NO_ERROR )
{
// handle error
}
// now this request will use internal memory again.
}
else
{
// handle error
}
}
else
{
// handle error
}
mvIMPACT.acquire.Device
This class and its functions represent an actual device detected by this interface in the current sys...
Definition Device.java:52
mvIMPACT.acquire.FunctionInterface
The function interface to devices supported by this interface.
Definition FunctionInterface.java:34
mvIMPACT.acquire.ImageRequestControl
A helper class to control the way an image request will be processed.
Definition ImageRequestControl.java:15
mvIMPACT.acquire.ImageRequestControl.getRequestToUse
PropertyI getRequestToUse()
An integer property defining which request object shall be used for the next image request.
Definition ImageRequestControl.java:186
mvIMPACT.acquire.PropertyI.write
PropertyI write(int value, int index)
Writes one value to the property.
Definition PropertyI.java:350
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
pRequest[in] A const pointer to the request object to configure

◆ imageRequestReset()

int imageRequestReset ( int requestCtrlNr,
int mode )

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
requestCtrlNr[in] The mvIMPACT.acquire.ImageRequestControl for which all the requests shall be cancelled.
mode[in] Currently unsupported. MUST be set 0.

◆ imageRequestResultQueueElementCount() [1/2]

int imageRequestResultQueueElementCount ( )

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

◆ imageRequestResultQueueElementCount() [2/2]

int imageRequestResultQueueElementCount ( int queueNr)

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
Parameters
queueNr[in] The result queue to be queried.

◆ imageRequestSingle() [1/3]

int imageRequestSingle ( )

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.getRequestCount(). 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.getAcquisitionStartStopBehaviour() is set to mvIMPACT.acquire.TAcquisitionStartStopBehaviour.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

◆ imageRequestSingle() [2/3]

int imageRequestSingle ( ImageRequestControl imageRequestControl)

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.getRequestCount(). 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.getAcquisitionStartStopBehaviour() is set to mvIMPACT.acquire.TAcquisitionStartStopBehaviour.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
Parameters
imageRequestControl[in] 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.getSetting()).

◆ imageRequestSingle() [3/3]

int imageRequestSingle ( ImageRequestControl imageRequestControl,
int[] requestUsed )

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.getRequestCount(). 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.getAcquisitionStartStopBehaviour() is set to mvIMPACT.acquire.TAcquisitionStartStopBehaviour.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
Parameters
imageRequestControl[in] 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.getSetting()).
requestUsed[out] This variable receives the number of the mvIMPACT.acquire.Request which will be used to process this request.

◆ imageRequestUnlock()

int imageRequestUnlock ( int nr)

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 = new FunctionInterface( pDev );
final long rc = fi.requestCount();
for( long i=0; i<rc; i++ )
{
fi.imageRequestUnlock( ( int )i );
}
mvIMPACT.acquire.FunctionInterface.imageRequestUnlock
int imageRequestUnlock(int nr)
Unlocks the request for the driver again.
Definition FunctionInterface.java:814

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
nr[in] The number of the request to unlock. This is typically a value returned from a call to mvIMPACT.acquire.FunctionInterface.imageRequestWaitFor.

◆ imageRequestWaitFor() [1/2]

int imageRequestWaitFor ( int timeout_ms)

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.TDMR_ERROR.DEV_WAIT_FOR_REQUEST_FAILED. To find out possible reasons for this error, look at the corresponding explanation.
Parameters
timeout_ms[in] 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. 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.getResultQueue() BEFORE calling mvIMPACT.acquire.FunctionInterface.imageRequestSingle.

◆ imageRequestWaitFor() [2/2]

int imageRequestWaitFor ( int timeout_ms,
int queueNr )

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.TDMR_ERROR.DEV_WAIT_FOR_REQUEST_FAILED. To find out possible reasons for this error, look at the corresponding explanation.
Parameters
timeout_ms[in] 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.
queueNr[in] 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.getResultQueue() BEFORE calling mvIMPACT.acquire.FunctionInterface.imageRequestSingle.

◆ isRequestNrValid()

boolean isRequestNrValid ( int nr)

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

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

◆ isSettingAvailable() [1/3]

int isSettingAvailable ( String name)

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
name[in] The name or the full path under where the setting is located.

◆ isSettingAvailable() [2/3]

int isSettingAvailable ( String name,
int storageLocation )

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
name[in] The name or the full path under where the setting is located.
storageLocation[in] The location of the setting.

◆ isSettingAvailable() [3/3]

int isSettingAvailable ( String name,
int storageLocation,
int scope )

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
name[in] The name or the full path under where the setting is located.
storageLocation[in] The location of the setting.
scope[in] Specifies the scope of this operation.

◆ loadAndDeleteSettingFromStack()

int loadAndDeleteSettingFromStack ( )

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() [1/3]

int loadSetting ( String name)

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.TStorageFlag.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.TStorageFlag.sfNative should be specified. It's not allowed to combine mvIMPACT.acquire.TStorageFlag.sfFile and mvIMPACT.acquire.TStorageFlag.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.TDeviceInterfaceLayout.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 VersionLoading an XML settings file created with Impact Acquire version < 2.9.0Loading an XML settings file created with Impact Acquire version 2.9.0 - 2.10.1Loading 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.TDeviceInterfaceLayout.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.getProduct() 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
name[in] The name or the full path under where the setting is located. and how this information shall be interpreted.

◆ loadSetting() [2/3]

int loadSetting ( String name,
int storageFlags )

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.TStorageFlag.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.TStorageFlag.sfNative should be specified. It's not allowed to combine mvIMPACT.acquire.TStorageFlag.sfFile and mvIMPACT.acquire.TStorageFlag.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.TDeviceInterfaceLayout.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 VersionLoading an XML settings file created with Impact Acquire version < 2.9.0Loading an XML settings file created with Impact Acquire version 2.9.0 - 2.10.1Loading 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.TDeviceInterfaceLayout.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.getProduct() 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
name[in] The name or the full path under where the setting is located.
storageFlags[in] The flags which define which information shall be read from the location and how this information shall be interpreted.

◆ loadSetting() [3/3]

int loadSetting ( String name,
int storageFlags,
int scope )

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.TStorageFlag.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.TStorageFlag.sfNative should be specified. It's not allowed to combine mvIMPACT.acquire.TStorageFlag.sfFile and mvIMPACT.acquire.TStorageFlag.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.TDeviceInterfaceLayout.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 VersionLoading an XML settings file created with Impact Acquire version < 2.9.0Loading an XML settings file created with Impact Acquire version 2.9.0 - 2.10.1Loading 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.TDeviceInterfaceLayout.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.getProduct() 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
name[in] The name or the full path under where the setting is located.
storageFlags[in] The flags which define which information shall be read from the location and how this information shall be interpreted.
scope[in] Specifies where the information is located.

◆ loadSettingFromDefault() [1/2]

int loadSettingFromDefault ( )

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

◆ loadSettingFromDefault() [2/2]

int loadSettingFromDefault ( int scope)

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
Parameters
scope[in] Specifies where the information is located.

◆ loadSettingFromStack()

int loadSettingFromStack ( )

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

◆ requestCount()

long requestCount ( )

Returns the number of available request objects.

See also
mvIMPACT.acquire.SystemSettings.getRequestCount() to change the number of request objects
Returns
Returns the number of available request objects.

◆ saveCurrentSettingOnStack() [1/2]

int saveCurrentSettingOnStack ( )

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.

// ...
final int Apply = 1;
final int Discard = 2;
// ...
FunctionInterface fi = getFunctionInterfaceFromSomewhere();
fi.saveCurrentSettingOnStack();
final int option = enterSectionThatModifiesDeviceSettings();
if( option == Discard )
{
fi.loadAndDeleteSettingFromStack(); // revert all changes just applied without worrying about what these changes actually are
}
else if( option == Apply )
{
fi.deleteSettingFromStack(); // remove the setting from the stack, but keep changes
}
mvIMPACT.acquire.FunctionInterface.deleteSettingFromStack
int deleteSettingFromStack()
Deletes the last setting from the setting stack.
Definition FunctionInterface.java:380
mvIMPACT.acquire.FunctionInterface.loadAndDeleteSettingFromStack
int loadAndDeleteSettingFromStack()
loads the last setting from the setting stack and then removes this setting from the stack.
Definition FunctionInterface.java:1181
mvIMPACT.acquire.FunctionInterface.saveCurrentSettingOnStack
int saveCurrentSettingOnStack(int storageFlags)
Saves the current setting on the setting stack.
Definition FunctionInterface.java:1307

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

information shall be stored.

◆ saveCurrentSettingOnStack() [2/2]

int saveCurrentSettingOnStack ( int storageFlags)

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.

// ...
final int Apply = 1;
final int Discard = 2;
// ...
FunctionInterface fi = getFunctionInterfaceFromSomewhere();
fi.saveCurrentSettingOnStack();
final int option = enterSectionThatModifiesDeviceSettings();
if( option == Discard )
{
fi.loadAndDeleteSettingFromStack(); // revert all changes just applied without worrying about what these changes actually are
}
else if( option == Apply )
{
fi.deleteSettingFromStack(); // remove the setting from the stack, but keep changes
}

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
Parameters
storageFlags[in] The flags which define which information shall be stored and how this information shall be stored.

◆ saveSetting() [1/3]

int saveSetting ( String name)

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.TStorageFlag.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.TStorageFlag.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
Parameters
name[in] The name or the full path under which this setting shall be stored information shall be stored.

◆ saveSetting() [2/3]

int saveSetting ( String name,
int storageFlags )

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.TStorageFlag.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.TStorageFlag.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
Parameters
name[in] The name or the full path under which this setting shall be stored
storageFlags[in] The flags which define which information shall be stored and how this information shall be stored.

◆ saveSetting() [3/3]

int saveSetting ( String name,
int storageFlags,
int scope )

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.TStorageFlag.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.TStorageFlag.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
Parameters
name[in] The name or the full path under which this setting shall be stored
storageFlags[in] The flags which define which information shall be stored and how this information shall be stored.
scope[in] Specifies where the information shall be stored.

◆ saveSettingToDefault() [1/2]

int saveSettingToDefault ( )

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

◆ saveSettingToDefault() [2/2]

int saveSettingToDefault ( int scope)

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
Parameters
scope[in] Specifies where the information shall be stored.

◆ swigRelease()

static long swigRelease ( FunctionInterface obj)
staticprotected

◆ updateRequests()

void updateRequests ( )

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.getRequestCount() 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:

See also
mvIMPACT.acquire.SystemSettings.getRequestCount()

Member Data Documentation

◆ swigCMemOwn

transient boolean swigCMemOwn
protected