Working With Settings

As already mentioned in the Quickstart chapter, settings contain all the parameters that are needed to prepare and program the device for the image capture. So for the user a setting is the one and only place where all the necessary modifications can be applied to achieve the desired form of data acquisition.

After a device has been initialized, the user will have access to a single setting named 'Base'. For most applications, this will be sufficient, as most applications just require the modification of a few parameters during start up and then at runtime these parameters stay constant.

This behavior can be achieved in two general ways:

• by settings the desired properties after the device has been initialized and before the image acquisition starts
• by setting up the device once interactively or with a small application and then store this parameter set and provide it as part of the application. During the device is initialized these set of parameters then can be used to set up the device

The first approach has the advantage, that no additional files are needed by the application, but modifying the acquisition parameters might force you recompile your code.

The second method typically results in a XML file containing all the parameters that can be shipped together with the application. The application in that case just calls a function to load a setting after the device has been initialized. Here parameters can be modified without the need to rebuild the application itself, but at least one additional file is needed and this file might be corrupted by unauthorized users leading the application to malfunction.

The function needed to load such a setting is DMR_LoadSetting(). A setting can be stored either by using one of the provided interactive GUI tools or by calling the function DMR_SaveSetting()

Working With More Than One Setting (device specific interface layout only)

Note

Features described in this section are available for the device specific interface layout only. See 'GenICam' vs. 'DeviceSpecific' Interface Layout for details.

Sometimes applications require the modification of parameters at runtime. This might become necessary e.g. when different regions of the image shall be captured at different times or when e.g. the exposure time must be adapted to the environment or for some other reason.

For the latter example, it's sufficient to acquire an image and use the image to determine the necessary exposure time for the next image from the acquired data and then set the expose time for the next acquisition and send a new image request to the device.

Modifying the AOI all the time might be tedious and sometimes it might be necessary to modify a large number of parameters back and forth. Here it would be more preferable to have two sets of parameters and tell the driver which setting to use for an acquisition when sending the request down to the driver.

To meet this requirement the Impact Acquire interface offers a method to create an arbitrary number of parameters.

A new setting can be created like this:

HOBJ hProp;
HLIST hSettingOne, hSettingTwo;
HDRV hDrv = getDriverHandleFromSomewhere();
DMR_CreateSetting( hDrv, "one", 0, &hSettingOne ) ;
DMR_CreateSetting( hDrv, "two", 0, &hSettingTwo ) ;
OBJ_GetHandle( hSettingOne, "Gain_dB", &hProp ) ;

Settings Are Structured In Hierarchies

In order to allow the modification of certain parameters in an easy and natural way, settings are organized in a hierarchical structure. In default state (after a device has been initialized the first time or without stored new settings) every device offers just one setting called 'Base'.

Each new setting the user can create will be derived directly or indirectly from this setting. So after the user has created new settings like in the source sample from above these new parameter sets still depend on the 'Base' setting:

Base
  |- one
  |- two

When now modifying a parameter in the setting 'Base' this will have direct impact on the new settings 'one' and 'two'. So this will provide a convenient way to change a parameter globally. Of course this is not always desired as then creating new settings wouldn't make any sense.

Modifying a parameter in one of the derived settings 'one' or 'two' will NOT influence the 'Base' or the other setting.

Furthermore modifying the same parameter in the 'Base' setting AFTER modifying the same parameter in one of the derived settings will NOT modify the derived setting anymore BUT will still modify in the setting that hasn't 'overwritten' the parameter:

Note

Assuming that 'Base' contains a property 'Gain_dB' with a value or 5.25:

Base ('Gain_dB = 5.25')
  |- one ('Gain_dB = 5.25')
  |- two ('Gain_dB = 5.25')

Note

Now setting the property 'Gain_dB' in setting 'one' to a new value of 3.3 will result in this:

Base ('Gain_dB = 5.25')
  |- one ('Gain_dB = 3.3')
  |- two ('Gain_dB = 5.25')

Note

Now setting the property 'Gain_dB' in setting 'Base' to a new value of 4.0 will result in this:

Base ('Gain_dB = 4.0')
  |- one ('Gain_dB = 3.3')
  |- two ('Gain_dB = 4.0')

Note

Setting 'one' won't be affected as it has already overwritten the value.

HLIST hSettingOne, hSettingTwo;
HOBJ hProp, hBaseProp;
HLIST hBase;
 
HDRV hDrv = getDriverHandleFromSomewhere();
DMR_CreateSetting( hDrv, "one", 0, &hSettingOne ) ;
DMR_CreateSetting( hDrv, "two", 0, &hSettingTwo ) ;
OBJ_GetHandle( hSettingOne, "Gain_dB", &hProp );
DMR_FindList( pDev->hDrv(), 0, dmltSetting, 0, &hBase )
OBJ_GetHandle( hBase, "Gain_dB", &hBaseProp );
OBJ_SetF( hProp, 3.3 );
OBJ_SetF( hBaseProp, 4.0 );
// now we have:
// Base ('Gain_dB = 4.0')
//   |- one ('Gain_dB = 3.3')
//   |- two ('Gain_dB = 4.0')

However the original parent <-> child relationship can be restored by calling the corresponding restore to default method for the property in question:

HLIST hSettingOne, hSettingTwo;
HOBJ hProp, hBaseProp;
HLIST hBase;
HDRV hDrv = getDriverHandleFromSomewhere();
 
DMR_CreateSetting( hDrv, "one", 0, &hSettingOne ) ;
DMR_CreateSetting( hDrv, "two", 0, &hSettingTwo ) ;
OBJ_GetHandle( hSettingOne, "Gain_dB", &hProp );
DMR_FindList( pDev->hDrv(), 0, dmltSetting, 0, &hBase )
OBJ_GetHandle( hBase, "Gain_dB", &hBaseProp );
OBJ_SetF( hProp, 3.3 );
OBJ_SetF( hBaseProp, 4.0 );
// now we have:
// Base ('Gain_dB = 4.0')
//   |- one ('Gain_dB = 3.3')
//   |- two ('Gain_dB = 4.0')
OBJ_RestoreDefault( hProp );
// now we have:
// Base ('Gain_dB = 4.0')
//   |- one ('Gain_dB = 4.0')
//   |- two ('Gain_dB = 4.0')
OBJ_SetF( hBaseProp, 5.0 );
// now we have:
// Base ('Gain_dB = 5.0')
//   |- one ('Gain_dB = 5.0')
//   |- two ('Gain_dB = 5.0')

Even the 'Base' setting has a default value for each property, that can be restored in the same way and affects all derived settings, that still refer to that original value :

HLIST hSettingOne, hSettingTwo;
HOBJ hProp, hBaseProp;
HLIST hBase;
 
HDRV hDrv = getDriverHandleFromSomewhere();
DMR_CreateSetting( hDrv, "one", 0, &hSettingOne ) ;
DMR_CreateSetting( hDrv, "two", 0, &hSettingTwo ) ;
OBJ_GetHandle( hSettingOne, "Gain_dB", &hProp );
DMR_FindList( pDev->hDrv(), 0, dmltSetting, 0, &hBase )
OBJ_GetHandle( hBase, "Gain_dB", &hBaseProp );
OBJ_SetF( hProp, 3.3 );
OBJ_SetF( hBaseProp, 4.0 );
// now we have:
// Base ('Gain_dB = 4.0')
//   |- one ('Gain_dB = 3.3')
//   |- two ('Gain_dB = 4.0')
OBJ_RestoreDefault( hBaseProp );
  // now we have:
  // Base ('Gain_dB = <driver default value>')
  //   |- one ('Gain_dB = 3.3')
  //   |- two ('Gain_dB = <driver default value>')

Defining Which Setting To Use

When now the user has created all the parameter sets he needs for the application and has modified all the parameters to meet his requirements the only thing he needs to do afterwards to switch from one setting to another is to send the parameter set to use down to the device with the image request.

This can be done by modifying the property 'setting' in an image request control. An image request Control is an object that defines the behavior of the capture process. Each time an image is requested from the driver the user can pass the image request control to be used as a parameter of the request.

HLIST hSettingOne, hSettingTwo;
HOBJ hGainS1Prop, hGainS2Prop, hSettingProp;
HLIST hReqCtrl;
 
HDRV hDrv = getDriverHandleFromSomewhere();
DMR_CreateSetting( hDrv, "one", 0, &hSettingOne ) ;
DMR_CreateSetting( hDrv, "two", 0, &hSettingTwo ) ;
OBJ_GetHandle( hSettingOne, "Gain_dB", &hGainS1Prop );
OBJ_GetHandle( hSettingTwo, "Gain_dB", &hGainS2Prop );
DMR_FindList( pDev->hDrv(), 0, dmltRequestCtrl, 0, & hReqCtrl)
OBJ_GetHandle( hBase, "Setting", &hSettingProp);
OBJ_SetF( hGainS1Prop, 3.3 );
OBJ_SetF( hGainS2Prop, 4.0 );
OBJ_SetS( hSettingProp, "one" );
// request an image with the parameters of setting 'one'
DMR_ImageRequestSingle( hDrv, hSettingOne & 0xFFFF, 0 );
OBJ_SetS( hSettingProp, "two" );
// request an image with the parameters of setting 'two'
DMR_ImageRequestSingle( hDrv, hSettingTwo & 0xFFFF, 0 );