mvIMPACT Acquire SDK C++
'GenICam' vs. 'DeviceSpecific' Interface Layout

Preface

Note
Read this first in order to find out if the whole page might be irrelevant for you/your application!
All recent MATRIX VISION devices and all supported third party devices will support the GenICam interface layout only! See here to find out which device supports which interface layout: Which Interface Is Supported By Which Device? . If your application only works with devices supporting a single interface layout you may chose to skip this page!

As the GenICam interface layout offers a much greater flexibility and allows access to all the features a device has to offer the DeviceSpecific interface layout for GenICam compliant devices has been declared deprecated by now. New applications should only use the DeviceSpecific interface layout for non GenICam compliant devices. Also for existing applications it is recommended to switch to the GenICam interface layout if possible. As mentioned earlier the impact on the applications code is not that high and the DeviceSpecific interface provides access to a subset of features only.

Which Interface Is Supported By Which Device?

All devices except some GigE Vision cameras manufactured by MATRIX VISION will support a single interface layout only. The following table will provide an overview about available interface layouts.

ProductDevice SpecificGenICam
mvBlueCOUGAR-S
mvBlueCOUGAR-X(D)
mvBlueCOUGAR-XT
3rd party GEV device
mvBlueFOX
mvBlueFOX3
3rd party U3V device
mvBlueGEMINI
mvBlueNAOS
mvBlueSIRIUS
mvDELTA
mvSIGMA
mvGAMMA
mvTITAN
mvHYPERION
mvVirtualDevice
mvV4L2

Attention
For backward compatibility devices supporting both interface layouts will be intialised using the device specific layout if an application does not explicitly select the GenICam one!

The Differences Between The Interface Layouts

Some mvIMPACT Acquire devices can be used with different interface layouts. The interface layout affects the way properties and methods that can be accessed using the SDK are presented to the application. For example controlling the exposure time of a camera using the device specific interface layout might require to write to an integer property Expose_us that can be found under the category Camera while when using the GenICam interface layout this might require to write to a floating point property ExposureTime under the category ImageFormatControl.

The following figure shows an excerpt to visualise the differences between the interface layouts:

Example of the properties differences of section Image Setting and Digital I/O (left: GenICam, right: device specific)
Attention
There is one fundamental difference in behaviour that must be kept in mind when designing applications: All the features presented under the GenICam feature tree will be written directly to the device whenever accessed. When using the DeviceSpecific interface layout these changes will be applied starting with the next image request that is send to the driver AFTER changing the feature. This has a notable consequence: Requesting X images and then changing e.g. the exposure time and requesting another Y images will in DeviceSpecific interface layout result in exactly X images using exposure time A and Y frames using exposure time B. In GenICam interface layout however the changed exposure time might work sooner, depending on whether the driver is already done capturing the X frames with exposure time A or not. So if a synchronous/defined change of the exposure time is wanted some extra care must be taken in GenICam interface layout. Either the capture process must be ended, the feature(s) must be changed and then the capture process must be started again or the change must be applied at exactly the right time, while right time then has to be defined by the application.

Choosing The Right Interface Layout

The interface layout to use can be selected BEFORE the device is initialized by modifying the property InterfaceLayout in the device property list. Valid values for this property are defined and described by the enumeration mvIMPACT::acquire::TDeviceInterfaceLayout.

How to select an interface layout using one of the GUI based tools that come with the mvIMPACT Acquire packages is described in the GUI section in the individual technical manuals describing the actual device (e.g. the technical manual for mvBlueCOUGAR-X devices.

How to select the interface layout from an application written using the mvIMPACT Acquire SDK can be seen in the source code of one of the example applications (e.g. GenICamInterfaceLayout.cpp ).

When To Use Which Interface Layout

The reason for different interface layouts comes from the fact that mvIMPACT Acquire supports a very wide range of hardware devices. Some of the driver packages allow control over devices that are compliant with on the international vision standards like GenICam, USB3 Vision, GigE Vision etc.. Other packages allow to access devices using a proprietary protocol. With the DeviceSpecific interface layout an attempt was made to achieve optimum compatibility between all MATRIX VISION devices while with the GenICam interface (which is only supported by a subset of MATRIX VISION devices) an application can achieve compatible behaviour between devices from a growing range of device vendors that build cameras and other hardware that complies with one of the standards mentioned above. So depending on the application either one or the other layout might be best.

Load/Store Settings On The Device Or In A Settings File

When using the GenICam interface layout all features that are defined by the device firmware can also be stored in non-volatile device memory. The following image displays which part of the feature tree can be stored on the device and which features are affected by the load/save functions of the FunctionInterface class.

Load/Store setting behaviour
Note
Just residing under the GenICam feature tree does not guarantee that a feature is actually stored on the device when using the USerSetSave command. A device firmware defines for each feature in its GenICam-XML file is a feature can be stored in non-volatile device memory or not. Therefore each feature that defines a
<Streamable>Yes</Streamable>
node can store its current value on the device, all others can't. As there might be pretty good reasons for features not be storable on the device, the load/save functions of the FunctionInterface class do also respect this, thus might not store the value of certain features within the GenICam sub-tree. All other features however can be stored inside a mvIMPACT Acquire setting file but NOT on the device.