Impact Acquire SDK C++
Porting Existing Code

Table of Contents

This chapter contains a detailed description about changes in the interface that have been made, that either might break existing code or lead to the deprecation of certain functions and structures and data types.

For each release version of the interface where changes that are important for development have been introduced this chapter will contain a section that will explain as detailed as necessary what these changes are and how to modify the code to run with the latest version of the interface.

Apart from that possible impacts on existing applications will be described as well.

Normally there won't be changes that require the developer to change his code. However when changes have been made it will only take a few minutes to port code to the latest version of the interface when sticking to this document.

Porting Existing Code Written With Versions Smaller Than 1.3.0

General Changes

The large customer's feedback required some major revision of the initial version of the C++ wrapper code. Apart from that the link dependency to the mvPropHandling-lib has been eliminated and the mvDeviceManager.h now offers a complete 'C' compliant interface, which can be used from other programming languages like Delphi© or Visual Basic© as well.

To port existing code to the new version of the interface your complete application needs to be recompiled and re-linked with the mvDeviceManager-lib and should no longer directly link the mvPropHandling-lib.

If you encounter error message during the compilation please use the following list of changes to port your code:

  • the C++ wrapper no longer needs the 'mvPropHandling.h' and only links the 'mvDeviceManager' now. The direct dependency between user application and mvPropHandling-lib has been removed.
  • the type CompID has been removed and replaced by HOBJ, HDRV, HDEV and HLIST.
  • the function mvIMPACT::acquire::Device::driver_id() became mvIMPACT::acquire::Device::hDrv().
  • the function mvIMPACT::acquire::Device::device_id() became mvIMPACT::acquire::Device::hDev().
  • the function mvIMPACT::acquire::Component::id() became mvIMPACT::acquire::Component::hObj().
  • changes in the structure 'ImageBuffer':
  • UValue Method::call( UParams* pParams, size_t parCnt ) became int Method::call( const std::string& params, const std::string& delimiters) the union UValue has been removed completely from the interface.
  • NEW FUNCTION std::string mvIMPACT::acquire::Request::getParamS( TImageRequestParam param ) const; replaces:
    • mvIMPACT::acquire::ImageBuffer::pixelFormatStringRep (available via Request::getParamS)
    • mvIMPACT::acquire::RequestResult::stateStringRep (available via Request::getParamS)
    • mvIMPACT::acquire::RequestResult::resultStringRep (available via Request::getParamS)
  • size_t maxStringLength = DEFAULT_STRING_SIZE_LIMIT parameter removed in functions mvIMPACT::acquire::Property::readSArray and some others.
  • compiler warning 4786 disabled for the VS 6 compiler.
  • the complete 'C' API is imported into the namespace mvIMPACT::acquire now.
  • type MV_RESULT removed and replaced either by TDMR_ERROR or TPROPHANDLING_ERROR.
  • return type of mvIMPACT::acquire::ComponentAccess::changedCounter changed from unsigned long to unsigned int.
  • mvIMPACT::acquire::FunctionInterface::imageRequestSingle( int requestCtrlNr ) const became mvIMPACT::acquire::FunctionInterface::imageRequestSingle( int requestCtrlNr, int* pRequestUsed ) const and only returns an error code now. The 2nd parameter can be omitted, so this change does not break existing code.
  • new class ImageBufferDesc which handles allocated ImageBuffer structures.
  • adapted to new mvDeviceManager.h interface.

Advantages

These changes involve some advantages:

  • The user has to link the mvDeviceManager-lib only.
  • More code moved from the C++ wrapper into the libraries. Therefore, more updates and bugfixes can be done by simply exchanging the library without the need to recompile or re-link the application.
  • The interface can be used with other languages like Delphi© easily.
Warning
Applications compiled with older versions of this interface will NOT run with this version of the driver. It's mandatory to recompile your application. Major changes like them won't occur once the package leaves its beta stadium!

The class mvIMPACT::acquire::ImageBufferDesc

The class mvIMPACT::acquire::ImageBufferDesc no longer supports the constructors

explicit mvIMPACT::acquire::ImageBufferDesc( ImageBuffer* p,bool boTakeOwnership = false );
mvIMPACT::acquire::ImageBufferDesc
A wrapper class to handle mvIMPACT::acquire::ImageBuffer structures.
Definition: mvIMPACT_acquire.h:7930

and

explicit mvIMPACT::acquire::ImageBufferDesc( const ImageBuffer& source );

The reason for this change is an enhanced method of image buffer handling. The user can now allocate complete image buffers including memory for the pixel data in the same format as the driver with the new constructor

explicit mvIMPACT::acquire::ImageBufferDesc( TImageBufferPixelFormat pixelFormat, int width, int height );

The image buffers handled by the class ImageBufferDesc are now reference counted resulting in a more powerful image management. However these means that calling the normal copy constructor will NOT allocate new memory for the buffer describing structure or the pixel data. So modifying the object created with the copy constructor will also modify the original object. To create a deep copy of the image the function mvIMPACT::acquire::ImageBufferDesc::clone( void ) const can be used. Porting existing code should be straight forward:

Example

(taken from the ImpactControlCenter source code)

ImageBufferDesc rgb_img( m_CurrentImage );
ImageBuffer* pRGB = rgb_img.getBuffer();
ImageBuffer* pCur = m_CurrentImage.getBuffer();
pRGB->vpData = new char[ pCur->iWidth * pCur->iHeight * 3 ];
ConvertYUVImageToRGB( pCur, pRGB );
SaveBMP( fileDlg.GetPathName().GetBuffer(), (const char*)pRGB->vpData, pRGB->iWidth, pRGB->iHeight, pRGB->pChannels[0].iLinePitch, pRGB->pChannels[0].iPixelPitch*8 );
delete [] pRGB->vpData;

became

ImageBuffer* pCur = m_CurrentImage.getBuffer();
ImageBufferDesc rgb_img( ibpfRGBx888Packed, pCur->iWidth, pCur->iHeight );
ImageBuffer* pRGB = rgb_img.getBuffer();
ConvertYUVImageToRGB( pCur, pRGB );
SaveBMP( fileDlg.GetPathName().GetBuffer(), (const char*)pRGB->vpData, pRGB->iWidth, pRGB->iHeight, pRGB->pChannels[0].iLinePitch, pRGB->pChannels[0].iPixelPitch*8 );

Which is shorter and more logical.

Porting Existing Code Written With Versions Smaller Than 1.4.0

  • typedef for IntDict and FloatDict removed from interface.
  • Replace
    • each occurrence of FloatDict by
      std::vector<std::pair<std::string, double> >
    • each occurrence of IntDict by
      std::vector<std::pair<std::string, int> >
  • class local enum for Property limits made global.
  • Property::minValue became plMinValue
  • Property::maxValue became plMaxValue
  • Property::stepWidth became plStepWidth
  • mvIMPACT::acquire::RTCtrProgram::programSize became mvIMPACT::acquire::RTCtrProgram::getProgramSize.

These changes where necessary for creating the .NET interface and might force you to change existing code.

The string property Device::userData, which has been introduced in version 1.3.8 of the interface has been replaced by a much more flexible method to handle user data in the devices non-volatile memory. See the description of the class's mvIMPACT::acquire::UserData and mvIMPACT::acquire::UserDataEntry for details.

Porting Existing Code Written With Versions Smaller Than 1.5.0

General Changes

The public properties mvIMPACT::acquire::IOSubSystem::inputRegister and mvIMPACT::acquire::IOSubSystem::outputRegister have been removed to achieve a more general class layout. The same information is available via other functions like e.g. mvIMPACT::acquire::IOSubSystem::readInputRegister.

Deprecated Stuff

Some functions have been declared deprecated. This means the are still part of the interface, but their use is not recommended anymore and they might be removed in future releases of the interface. To remove deprecated calls from your code

Porting Existing Code Written With Versions Smaller Than 1.6.0

Replace each occurrence of mvIMPACT::acquire::ImageRequestControlVector by std::vector<mvIMPACT::acquire::ImageRequestControl*>

Deprecated Stuff

Some functions have been declared deprecated. This means the are still part of the interface, but their use is not recommended anymore and they might be removed in future releases of the interface. To remove deprecated calls from your code

Porting Existing Code Written With Versions Smaller Than 1.8.0

The declaration of the function mvIMPACT::acquire::EventSubSystem::waitFor has been modified. The old declaration looked like this:

int mvIMPACT::acquire::EventSubSystem::waitFor( int timeout_ms, TDeviceEventType mask, TDeviceEventType& resultMask );

while the new one looks like this:

EventWaitResults mvIMPACT::acquire::EventSubSystem::waitFor( int timeout_ms, TDeviceEventType mask );

This was necessary to achieve a constant interface under .NET and also is more flexible for future enhancements.

Porting Existing Code Written With Versions Smaller Than 1.9.0

The already declared as deprecated class mvIMPACT::acquire::Settings has been modified. Its member cameraSetting is no longer of type mvIMPACT::acquire::CameraSettings, but mvIMPACT::acquire::CameraSettingsBlueFOX now as mvIMPACT::acquire::CameraSettings has been declared as deprecated as well and the usage of deprecated types and functions will result in compile time warnings now. Apart from that only the mvBlueFOX supported all the properties offered by this class anyway. So if you have written code like this:

// ...
mvIMPACT::acquire::Settings cs(pDev);
// ...
mvIMPACT::acquire::CameraSettings& = cs.cameraSetting;

you can rewrite it like this:

// ...
mvIMPACT::acquire::Settings cs(pDev);
// ...
mvIMPACT::acquire::CameraSettingsBlueFOX& = cs.cameraSetting;
mvIMPACT::acquire::CameraSettingsBlueFOX
mvBlueFOX related camera settings(Device specific interface layout only).
Definition: mvIMPACT_acquire.h:19641

or (better) you use one of the device specific class, as the class mvIMPACT::acquire::Settings has been declared deprecated as well.

Device specific replacement:

Porting Existing Code Written With Versions Smaller Than 1.10.0

Deprecated Stuff

All versions of the functions mvIMPACT::acquire::Request::getInfo and mvIMPACT::acquire::Request::getResult have been declared deprecated. They might disappear in future releases of this interface. Replace calls to these function by directly accessing the newly published properties in the class mvIMPACT::acquire::Request such as mvIMPACT::acquire::Request::requestResult or mvIMPACT::acquire::Request::infoGain_dB. This is more efficient and much more flexible.

Changed Compile-time Behavior

Functions and classes that have been declared deprecated for some time now have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes and functions that have been removed and their replacement:

Porting Existing Code Written With Versions Smaller Than 1.11.0

Functions and classes that have been declared deprecated for some time now have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Changed Run-time Behavior

Porting Existing Code Written With Versions Smaller Than 1.12.0

The release of version 1.12.0 of the Impact Acquire interface does no longer contain interface members, that have been declared as deprecated in previous versions. The following list can be used to port code to this release. These changes will NOT affect existing binaries, thus application compiled with code from this list, will continue to work, but can't be built with a new interface release.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Changed Run-time Behavior

  • The class mvIMPACT::acquire::Request did support a property 'UserData' for mvBlueCOUGAR-P and mvBlueLYNX-M7 devices. This feature has been renamed to 'ChunkUserData' and resides in a sublist now. Even though this feature has never been officially published it might have been used by existing applications and therefore might break existing binaries! When your application did or does use this property you need to change the name, rebuild and redistribute your software in order to work with newer driver versions.

Porting Existing Code Written With Versions Smaller Than 2.0.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

If re-building your application please note that when linking against the new export names of the display library, the display library on the target system must be updated as well.

Porting Existing Code Written With Versions Smaller Than 2.6.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

  • mvIMPACT::acquire::dilGeneric.
    When you still need this call mvIMPACT::acquire::Device::interfaceLayout.writeS("Generic") instead.

Porting Existing Code Written With Versions Smaller Than 2.7.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.10.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.12.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.15.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

  • mvIMPACT::acquire::cfUserAllocatedMemory.
  • mvIMPACT::acquire::PROPHANDLING_NO_USER_ALLOCATED_MEMORY.
  • mvIMPACT::acquire::ENoUserAllocatedMemory.
    There is NO direct replacement for all these things, as they haven't been used internally or externally anyway. Simply remove all references from your code.

Porting Existing Code Written With Versions Smaller Than 2.16.0

Changed Run-time Behavior

The support for the Generic interface layout has finally been removed. Please port your applications to use the interface layout mvIMPACT::acquire::dilGenICam instead. Systems depending on the generic interface layout will NO LONGER work starting from this version of Impact Acquire!

Porting Existing Code Written With Versions Smaller Than 2.17.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.20.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.25.0

Functions and classes that have been declared deprecated for some time have been removed from the interface. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed as the products supporting them are no longer available:

Changed Compile-time Behavior

  • mvIMPACT::acquire::GenICam::DeviceControl::mvDeviceSensor
  • mvIMPACT::acquire::GenICam::ImageFormatControl::mvDebayerAlgorithm
  • mvIMPACT::acquire::GenICam::ImageFormatControl::mvOffsetYSensorB
  • mvIMPACT::acquire::GenICam::ImageFormatControl::mvSensorLineOffsetSelector
  • mvIMPACT::acquire::GenICam::ImageFormatControl::mvSensorLineOffset
  • mvIMPACT::acquire::GenICam::ImageFormatControl::mvSensorLinePeriod
  • mvIMPACT::acquire::GenICam::AnalogControl::mvVCAL
  • mvIMPACT::acquire::GenICam::AnalogControl::mvVBLACK
  • mvIMPACT::acquire::GenICam::AnalogControl::mvVOFFSET
  • mvIMPACT::acquire::GenICam::mvOMAPPreviewConfig
  • mvIMPACT::acquire::GenICam::mvXLampControl
  • mvIMPACT::acquire::GenICam::mvSPIControl
  • mvIMPACT::acquire::GenICam::mvDACParams
  • mvIMPACT::acquire::GenICam::mvACCControl

Simply remove all references from your code.

Porting Existing Code Written With Versions Smaller Than 2.27.0

Functions and classes that have been declared deprecated for a long time have been removed from the interface as they also have from the SFNC some time ago. This will not break existing binaries, but will force you to change your code during rebuilds when deprecated code was used by your application.

List of classes, functions and data types that have been removed as they have been declared deprecated for a very long time

Changed Compile-time Behavior

  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsUserDefinedName
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsSerialNumber
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsEVENTDATA
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsEVENT
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsPACKETRESEND
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsWRITEMEM
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionalCommandsConcatenation
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedIPConfigurationLLA
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedIPConfigurationDHCP
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedIPConfigurationPersistentIP
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevCurrentIPConfiguration

All the features above might be accessible using the mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOptionSelector and mvIMPACT::acquire::GenICam::TransportLayerControl::gevSupportedOption if supported by the device.

  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestEntrySelector
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestXMLMajorVersion
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestXMLMinorVersion
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestXMLSubMinorVersion
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestSchemaMajorVersion
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestSchemaMinorVersion
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestPrimaryURL
  • mvIMPACT::acquire::GenICam::TransportLayerControl::gevManifestSecondaryURL

All the features above might be accessible using the mvIMPACT::acquire::GenICam::DeviceControl::deviceManifestEntrySelector and other manifest table related features in the mvIMPACT::acquire::GenICam::DeviceControl category if supported by the device.

If the device you are using depends on any of the removed properties and does not support the recommended replacement derive from the existing classes the features have been removed from and add the features you need there. Therefore the code from an earlier release of this SDK can be used to copy most of the code from.

Note
Most likely the Raw feature uses a different unit/data type than the one without the Raw postfix. Please take care when changing your code!

Porting Existing Code Written With Versions Smaller Than 2.28.0

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.32.0

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.34.0

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.37.0

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Porting Existing Code Written With Versions Smaller Than 2.38.0

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

  • The property mvIMPACT::acquire::SystemSettings::workerPriority as well as the enumeration mvIMPACT::acquire::TThreadPriority have been removed from the public interface. Existing binaries will not be affected but if an application wants to continue to use this property the mvIMPACT::acquire::DeviceComponentLocator class must be used from now on to bind this property manually. This however is strongly discouraged! Modifying this property does not provide any benfits to an application.

Porting Existing Code Written With Versions Smaller Than 2.47.0

List of classes, functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

Changed Run-time Behavior

As a consequence of the removal of the event related classes mentioned in the previous the underlying C-API serving these classes has been removed as well. If an application made use of this API it needs to be recompiled and linked before it can work with Impact Acquire 2.47.0 of higher. Otherwise the following symbols might be reported as unresolved:

  • DMR_EventWaitFor
  • DMR_EventGetData

Porting Existing Code Written With Versions Smaller Than 2.49.0

List of classes, functions and data types that have been moved to another namespace:

Changed Compile-time Behavior

  • mvIMPACT::acquire::labs::FirmwareUpdater
    The FirmwareUpdater class has moved from the mvIMPACT::acquire::labs namespace to mvIMPACT::acquire as it has been tested for a sufficient amount of time without any major issues. The API has been changed during that evaluation time and is supposed to be stable now. There is a suitable example as well now called FirmwareUpdate.cpp. Simply remove all occurrences of the labs namespace in connection with the updater class.

Porting Existing Code Written With Versions Smaller Than 3.0.0

The release of 3.0.0 of the Impact Acquire interface does no longer contain interface members, that have been declared as deprecated in previous versions. The following list can be used to port code to this release. These changes will NOT affect existing binaries, thus application compiled with code from this list, will continue to work, but can't be built with a new interface release.

Changed Compile-time Behavior

List of classes, functions and data types that have been removed and their replacement:

Deprecated Stuff

Frame Grabber Support

Note
Beginning with the release of 3.0.0 of Impact Acquire everything specifically related to frame grabber boards will be considered as deprecated and might be removed without further notice. No direct replacement will be provided for any of the classes, functions and data types!

List of frame grabber specific classes that have been declared deprecated:

List of frame grabber specific data types that have been declared deprecated:

Makefiles

Impact Acquire is shipped with CMake support for quite a while now (see Building And Linking Using CMake for details) and maintaining the traditional Makefiles that have been part of any Impact Acquire for a long time will soon come to an end. From this version onwards traditional Makefiles might be removed from example and GUI applications without further notice. Building using CMake is much easier and therefore should be preferred as soon as possible!

Porting Applications Written With The Generic interface Layout To Use The GenICam™ Interface Layout

The mvIMPACT::acquire::dilGeneric interface layout has been declared deprecated since version 1.11.37 of Impact Acquire and was removed from the interface in version 2.6.0. It has been replaced by a new interface layout mvIMPACT::acquire::dilGenICam. New applications should NOT be written using the mvIMPACT::acquire::dilGeneric interface layout, existing ones should be ported. Porting an application from one interface layout to the other in most cases will require less than one hour and will improve interoperability of the driver framework with different hardware platforms especially third party "GigE Vision" devices. When the generic interface was designed the idea was to have a look and feel which as closely matches the typical Impact Acquire interface layout in terms of where properties are located in the drivers property tree.

As a result of that e.g. all the digital I/O related features where created under "IOSubSystem" as Impact Acquire does. A "GigE Vision" device typically refers to digital I/O as "Lines" and these are located in the GenICam SFNC compliant category "DigitalIOControl". However, in earlier version of the GenICam SNFC documentation there have been no standard names for standard categories which resulted in different manufacturers using different names for essentially the same thing. This now made it quite difficult to locate the category for digital I/Os in a devices XML description file. Simply looking for one or more of the standard I/O features and then check for the category these features reside would have been an option, but then again there have been devices having 2 or more categories with almost identical names(e.g. one for the SFNC compliant I/O stuff and one with the additional I/O features added during the device design).

To sum it up: Analyzing the devices XML file and then make certain assumptions on which features fits where in Impact Acquire's property hierarchy turned out not to be such a brilliant idea and required constant modifications in the driver framework. This was a problem for both customers and developers at Balluff. In order not to break existing applications the current mvIMPACT::acquire::dilGeneric interface layout was left untouched and a new one (mvIMPACT::acquire::dilGenICam) was introduced. In terms of timing and overall behavior both interface layouts are identical. Internally they even share large portions of the code. The only difference, which can be seen from the outside is the location of the properties that are created from the GenICam XML files. Thus, code that locates and binds certain properties and methods might need to be changed in terms of the starting locations of the search calls.

In mvIMPACT::acquire::dilGeneric the layout did more or less (if locating the standard categories succeeded) look like this:

|
|- ImagingSubsystem
| |
| |- Setting
| |
| |- Setting Base // In GenICam interface layout only one capture setting is supported to understand how to use several settings have a look at the example section or the 'Working with settings' chapter
| | |
| | |- Camera // features extracted from the devices XML file
| | |
| | |- ImageFormatControl (see SFNC)
| | |- AcquisitionAndTriggerControl (see SFNC)
| | |- etc. // everything else, that is not part of the SFNC. This will be created 'as is', thus with the structure defined in the description file of the device
|
|- IOSubSystem
| |- LineSelector
| |- etc. // all other Digital I/O related features
|
|- System
| |
| |- GenTL // features extracted from the GenICam GenTL producers XML files
| | |
| | |-Stream0
| | |-Stream1
| | |-...
| | |-Stream(n-1)
| |
| |- TransportLayer
| |- CodeGeneration
| |- FileAccessControl
| |- etc. // various other features the influence the overall behavior of the driver
|
|- Info // various features providing information about the device, driver versions etc.
|
|
other features

while in mvIMPACT::acquire::dilGenICam now no assumptions are made and everything extracted from GenICam XML files ends up under the "Camera" category of the imaging sub-system:

|
|- ImagingSubsystem
| |
| |- Setting
| |
| |- Setting Base // In GenICam interface layout only one capture setting is supported to understand how to use several settings have a look at the example section or the 'Working with settings' chapter
| | |
| | |- Camera
| | |
| | |- GenICam // features extracted from the devices XML file
| | | |
| | | |- ImageFormatControl (see SFNC)
| | | |- AcquisitionAndTriggerControl (see SFNC)
| | | |- etc. // everything else, that is not part of the SFNC. This will be created 'as is', thus with the structure defined in the description file of the device
| | |
| | |- GenTL // features extracted from the GenICam GenTL producers XML files
| | |
| | |- Device
| | |- DataStream
| | |- etc.
|
|- System
| |
| |- CodeGeneration
| |- etc. // various other features the influence the overall behavior of the driver
|
|- Info // various features providing information about the device, driver versions etc.
|
|
other features

Notes about Impact Acquire Version 1.11.32 Or Higher And/Or Using mvBlueCOUGAR-X With Firmware 1.2.0 Or Higher

Balluff offers three different "Interface layouts" which are explained below:

  • "Device specific":
    • Compatibility mode regardless of type of Balluff device (frame grabber, USB or "GigE Vision" camera).
    • Additional layer which translates between modes (same functionality and naming of all functions and properties).
    • Recommended for users using different Balluff products in different applications with the same code base.
    • Some product specific features may not become available.
  • GenICam:
    • For users who are familiar with the standards "GigE Vision", "USB3 Vision", and GenICam.
    • Offers a one to one representation of the features described in the XML-file supplied by the device or the device vendor.
  • "Generic":
    • Has been declared deprecated and should not used for new applications. If possible applications using this interface should be ported to use the GenICam interface.
    • Just kept for backward compatibility.
    • Uses XML-wordings but groups the properties in a different way.
    • Behavior and usage are similar to the GenICam interface, but
      • some feature groups will be created at different locations
      • some small differences exist in the name and position of certain feature groups

The advantage of the latter two modes is that all features of the cameras become immediately available and are clearly marked whether they are part of the standard or company specific (mv headed).

Note
Third-party "GigE Vision" cameras can only be accessed via GenICam / Generic interface.

To define which interface layout shall be used an application can write the desired interface layout to the mvIMPACT::acquire::Device::interfaceLayout property. See the description of the class mvIMPACT::acquire::Device in the C++ documentation for an example.

ImpactControlCenter can also be configured to always use a desired interface layout when initialising a device.

Note
  • When using the latter two, between version 1.1.43 and version 1.2, there was a change needed in the naming and grouping of some properties for compliance with the SFNC (see http://www.genicam.org/ -> downloads) as listed below.
  • Using cameras with mvBlueCOUGAR-X firmware versions above 1.2.x.x in Generic or GenICam mode in combination with the renamed features therefore will require a change in the applications code and a recompilation. Also stored settings which referred to features that either have been renamed or removed or moved to a new location will no longer work correctly with that setting. Therefore these settings (either as XML files or in the Windows® Registry®) should be recreated.
  • Using cameras with mvBlueCOUGAR-X firmware above 1.2.x.x in "Device specific" mode in combination with the renamed features therefore will require Impact Acquire version 1.11.32 or higher but no recompilation. However devices running with a new firmware (1.2.x.x or greater) will not be fully functional with Impact Acquire drivers smaller than 1.11.32.

In order to make sure applications will continue to work with both new and old versions of the firmware one could of course enhance an existing application by

  • checking for the presence of the new feature(name) first and then
  • try the old name of the feature (if existent) as a fall-back.

Downgrading a camera with firmware 1.2.x.x to an earlier version is possible but not recommended due to continuous product improvement.

Feature naming changes from 1.1.43.0 to 1.2.x.x

To distinguish between Balluff and SFNC 1.5 features we introduced the prefix "mv". So some features have to be renamed. Besides that we made some adjustments to fulfill the "GenICam Standard Features Naming Convention" Specification (SFNC 1.5).

Note
# is a place holder for a number; ? for a letter.
  • AdvancedSettings (removed)
    • DeviceTemperatureUpperLimit ==> DeviceControl/mvDeviceTemperatureUpperLimit
    • DeviceTemperatureLowerLimit ==> DeviceControl/mvDeviceTemperatureLowerLimit
    • DeviceTemperatureLimitHysteresis ==> DeviceControl/mvDeviceTemperatureLimitHysteresis
    • DesiredAverageGreyValue_pc ==> AcquisitionControl/mvExposureAutoAverageGrey and AnalogControl/mvGainAutoAverageGrey(both features are mapped to the same register thus will always contain the same value)
    • TimeStampResetSource ==> TriggerSource when TriggerSelector == 'mvTimestampReset'
    • TimeStampResetActivation ==> TriggerActivation when TriggerSelector == 'mvTimestampReset'
    • ANDSelector ==> mvLogicGateControl/mvLogicGateANDSelector
      • AND# ==> mvLogicGateAND#
      • ANDSource? ==> mvLogicGateANDSource#
    • ORSelector ==> mvLogicGateControl/mvLogicGateORSelector
      • OR# ==> mvLogicGateOR#
      • ORSource? ==> mvLogicGateORSource#
  • ImageFormatControl
    • AcquisitionPixelClock ==> DeviceControl/mvDeviceClockFrequency
  • DeviceControl
    • SensorName ==> mvDeviceSensorName
    • SensorColorMode ==> mvDeviceSensorColorMode
    • FPGAVersion ==> mvDeviceFPGAVersion
    • FirmwareSource ==> mvDeviceFirmwareSource
  • AcquisitionControl
    • ExposureAutoLowerLimit ==> mvExposureAutoLowerLimit
    • ExposureAutoUpperLimit ==> mvExposureAutoUpperLimit
    • ExposureAutoSpeed ==> mvExposureAutoSpeed
    • ExposureAutoDelayImages ==> mvExposureAutoDelayImages
  • AnalogControl
    • GainAutoDelayImages==> mvGainAutoDelayImages
    • GainAutoLowerLimit ==> mvGainAutoLowerLimit
    • GainAutoUpperLimit==> mvGainAutoUpperLimit
    • GainAutoSpeed==> mvGainAutoSpeed
  • FFCControl ==> mvFFCControl:
    • FFCEnable ==> mvFFCEnable
    • CalibrationImageCount ==> mvFFCCalibrationImageCount
    • Calibrate ==> mvFFCCalibrate
  • HDRControl ==> mvHDRControl:
    • HDREnable ==> mvHDREnable
    • HDRMode ==> mvHDRPreset (use parameter set), mvHDRSelector (read/write parameter set)
  • ImageFormatControl
    • AcquisitionPixelClock ==> DeviceControl/mvDeviceClockFrequency
  • DeviceControl:
    • SensorName ==> mvDeviceSensorName
    • SensorColorMode ==> mvDeviceSensorColorMode
    • FPGAVersion ==> mvDeviceFPGAVersion
    • FirmwareSource ==> mvDeviceFirmwareSource
  • DigitalIOControl
    • LineSelector/LineSource
      • TemperatureOutOfRange ==> mvTemperatureOutOfRange
      • OR#OUT ==> mvLogicGateOR#Output
      • ExposureAndAcquisitionActive ==> mvExposureAndAcquisitionActive
      • LineDebounceTimeRisingEdge ==> mvLineDebounceTimeRisingEdge
      • LineDebounceTimeFallingEdge ==> mvLineDebounceTimeFallingEdge
  • CounterAndTimerControl
    • CounterSelector/CounterTriggerSource
      • High ==> removed (obsolete, now same as 'Off')
      • LineStart ==> removed (not SFNC 1.5)
      • LineEnd ==> removed (not SFNC 1.5)
    • TimerSelector/CounterTriggerSource
      • High/Low ==> removed (obsolete, now same as 'Off', Timer is running infinite)
      • LineStart ==> removed (not SFNC 1.5)
      • LineEnd ==> removed (not SFNC 1.5)
  • TransportLayerControl
    • GevStreamChannelSelector
      • GevSCBWControl ==> mvGevSCBWControl
      • GevSCBW ==> mvGevSCBW
  • UserSetControl
    • MvUserData ==> mvUserData