Dynamic Properties

Apart from the device specific functions which either require a handle to the device itself (HDEV) or to the devices interface(HDRV) there is a large set of device independent functions to set and read dynamic properties and execute certain functions from GUI applications. Handles to the properties and methods can be obtained via device specific functions like DMR_FindList() or DMR_CreateSetting().

These properties will be registered during the initialization of the device and will vary from device to device. With newer versions of the framework new properties will appear without the need to compile the application with new header files. Properties once published in the interface will remain there forever in order not to break existing code. However when writing applications for devices from different product families always check if a certain property is actually available. The function OBJ_CheckHandle() is meant to perform this kind of test.

All device independent function, which are meant to work with properties and methods, are prefixed with OBJ_.

A good example for a property might e.g. be the exposure time in us or the current number of frames per second. Properties provide the great advantage, that no special function for each possible setting offered by the device is needed. GUI applications like ImpactControlCenter can be developed, that allow to set every possible framework property without the need to know what settings are available and what they actually mean. The GUI application just determines the available properties at run time, thus with a new framework version being released the GUI application will display new properties and can even set and read values from/to this property without the need to rebuild the application. This provides user applications with a great degree of freedom.

In order to locate a certain property the basic approach will always look somehow like this:

//-----------------------------------------------------------------------------
HOBJ getFPSProp( HDRV hDriverInterface )
//-----------------------------------------------------------------------------
{
  TPROPHANDLING_ERROR objResult;
  TDMR_ERROR dmrResult;
  HOBJ hProp;
  HLIST hList;
 
  // try to locate the list for statistical information
  if( ( dmrResult = DMR_FindList( hDriverInterface, 0, dmltStatistics, 0, &hList ) ) == DMR_NO_ERROR )
  {
    // try to locate the property containing the current frames per second
    if( ( objResult = OBJ_GetHandle( hList, "FramesPerSecond", &hProp ) ) != PROPHANDLING_NO_ERROR )
    {
      printf( "OBJ_GetHandle failed: %d Handle: %d\n", objResult, hProp );
    }
  }
  else
  {
    printf( "DMR_FindList failed: %d\n", dmrResult );
  }
  return hProp;
}

To find out which properties are available and where please use the tool ImpactControlCenter or any other tool provided, which displays a hierarchical structure of all properties. Afterwards, the functions DMR_FindList() and OBJ_GetHandle() can be used to obtain a handle to the property.

Note

If a property is housed in a sublist of the list returned by the call to DMR_FindList() like e.g. the property 'W' in the sublist 'Aoi' of each setting, you should call OBJ_GetHandle() with the 'path' to that property.

Example

//-----------------------------------------------------------------------------
HOBJ getWidthProp( HDRV hDriverInterface )
//-----------------------------------------------------------------------------
{
  TPROPHANDLING_ERROR objResult;
  TDMR_ERROR dmrResult;
  HOBJ hProp;
  HLIST hBaseSetting;
 
  // try to locate the setting list "Base"
  if( ( dmrResult = DMR_FindList( hDriverInterface, "Base", dmltSetting, 0, & hBaseSetting) ) == DMR_NO_ERROR )
  {
    // try to locate the property containing the current width of the captured image
    if( ( objResult = OBJ_GetHandle( hBaseSetting, "Aoi/W", &hProp ) ) != PROPHANDLING_NO_ERROR )
    {
      printf( "OBJ_GetHandle failed: %d Handle: %d\n", objResult, hProp );
    }
  }
  else
  {
    printf( "DMR_FindList failed: %d\n", dmrResult );
  }
  return hProp;
}