C compliant interface reference

This is the documentation for developers who want to work with the C compliant interface of the driver. This interface represents the basis for the C++ interface but it can also be access with pure C-compilers or from other programming languages that can take advantage of C compliant exported dynamic library functions.

Note:

If a C++ compiler is available it is highly recommend to work with the C++ interface instead of this C interface as it is much easier to use. The complete C++ interface is available in source code and adds NO relevant overhead to the application. It internally calls the functions described in this interface and will greatly reduce the development time and will result in a more readable code without introducing any disadvantages.

Overview

The standard way of using this library roughly works like this:

Before any device can be accessed the user need to initialize the library. To this the functions DMR_Init() must be used. Calling this function for the first time will initialize internal data structures and will force the device manager to scan the system for recognized device types.

This function can be called multiple times, but for each time DMR_Init() is called the user must make sure that later, when this library is not needed anymore the function DMR_Close() is called, as otherwise resource leaks will occur.

After the library has been initialized successfully (the return value of most of the functions in this module will be an error code), the user can start to locate a certain device by using the function DMR_GetDevice(). When the corresponding device has been located, this device can be initialized or closed via calls to the functions DMR_OpenDevice() and DMR_CloseDevice()

Once a device has been initialized the user will receive a handle to the devices interface (HDRV). This handle is needed to call most of the other functions interacting with the actual device. All the functions called for a certain device will start with a leading DMR_. These include (among others) functions to capture and access images and functions to load a save settings made for this device.

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 driver 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 mvPropView can be developed, that allow to set every possible driver 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 driver being released the GUI application will display new properties and even allows to 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.

mvIMPACT image processing

When additional image processing of the captured images is required as well the mvIMPACT image processing library can be used in connection with this capture interface. All image processing functions however will ask for a special image buffer format. The device can deliver this format natively but the functions returning this data format will not by default be included into the interface thus allowing the usage of the capture interface only without the need to install the complete image processing library as well. To include the functions that will return mvIMPACT image processing library compliant buffers to the user application the main header of the library must be included BEFORE including the capture interface headers:

#include <vl_base.h>
#include <mvDeviceManager/Include/mvDeviceManager.h>

Getting started

This short section shows how to capture and display a live image together with the output of some statistical information with this interface under Windows®.

The complete source code can be found here: ExampleApplications_section_Continuous

First the library is initialized and a device is opened:

#define END_APPLICATION \
  printf( "Press any key to end the application.\n" ); \
  getch(); \
  return 0; \

// try to initialize the library.
if( ( result = DMR_Init( &hDMR ) ) != DMR_NO_ERROR )
{
  printf( "DMR_Init failed (code: %d)\n", result );
  END_APPLICATION;
}

// try to get access to the first recognized device in the system
if( ( result = DMR_GetDevice( &hDevice, dmdsmSerial, "*", 0, '*' ) ) != DMR_NO_ERROR )
{
  printf( "DMR_GetDevice failed (code: %d)\n", result );
  END_APPLICATION;
}

// try to initialize this device
if( ( result = DMR_OpenDevice( hDevice, &hDriverInterface ) ) != DMR_NO_ERROR )
{
  printf( "DMR_OpenDevice failed (code: %d)\n", result );
  END_APPLICATION;
}

In any thread function the handle to the device (HDEV) and the handle to the devices interface (HDRV) can now be used to capture images:

#define MAX_REQUESTS (3)

// prefill the default capture queue
for( i=0; i<MAX_REQUESTS; i++ )
{
 DMR_ImageRequestSingle( hDriverInterface, 0, 0 );
}

while( !g_boTerminated )
{
  result = DMR_ImageRequestWaitFor( hDriverInterface, 500, 0, &requestNr );
  if( result == DMR_NO_ERROR )
  {
    if( ( result = DMR_GetImageRequestBuffer( hDriverInterface, requestNr, &pIB ) ) == DMR_NO_ERROR )
    {
      // display the captured image using some kind of display function

      // inform the driver, that this request buffer is no longer needed by the user
      DMR_ImageRequestUnlock( hDriverInterface, requestNr );
      // request the next image
      DMR_ImageRequestSingle( hDriverInterface, 0, 0 );
    }
    else
    {
      printf( "DMR_GetImageRequestBuffer: ERROR! Code %d\n", result );
    }
  }
  else
  {
    printf( "DMR_ImageRequestWaitFor: ERROR! Code %d\n", result );
  }
}

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 mvPropView 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;
}

< prev. section: Chunk data format | top | next section: Example applications >