Impact Acquire SDK .NET
Porting Existing Code

Porting Existing Code Written With This Interface

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 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

  • mv.impact.acquire.TComponentFlag.cfUserAllocatedMemory.
  • mv.impact.acquire.TPROPHANDLING_ERROR.PROPHANDLING_NO_USER_ALLOCATED_MEMORY.
  • mv.impact.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 mv.impact.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

  • mv.impact.acquire.GenICam.DeviceControl.mvDeviceSensor.
  • mv.impact.acquire.GenICam.ImageFormatControl.mvDebayerAlgorithm
  • mv.impact.acquire.GenICam.ImageFormatControl.mvOffsetYSensorB
  • mv.impact.acquire.GenICam.ImageFormatControl.mvSensorLineOffsetSelector
  • mv.impact.acquire.GenICam.ImageFormatControl.mvSensorLineOffset
  • mv.impact.acquire.GenICam.ImageFormatControl.mvSensorLinePeriod
  • mv.impact.acquire.GenICam.AnalogControl.mvVCAL
  • mv.impact.acquire.GenICam.AnalogControl.mvVBLACK
  • mv.impact.acquire.GenICam.AnalogControl.mvVOFFSET
  • mv.impact.acquire.GenICam.mvOMAPPreviewConfig
  • mv.impact.acquire.GenICam.mvXLampControl
  • mv.impact.acquire.GenICam.mvSPIControl
  • mv.impact.acquire.GenICam.mvDACParams
  • mv.impact.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

  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsUserDefinedName
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsSerialNumber
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsEVENTDATA
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsEVENT
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsPACKETRESEND
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsWRITEMEM
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedOptionalCommandsConcatenation
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedIPConfigurationLLA
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedIPConfigurationDHCP
  • mv.impact.acquire.GenICam.TransportLayerControl.gevSupportedIPConfigurationPersistentIP
  • mv.impact.acquire.GenICam.TransportLayerControl.gevCurrentIPConfiguration

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

  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestEntrySelector
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestXMLMajorVersion
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestXMLMinorVersion
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestXMLSubMinorVersion
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestSchemaMajorVersion
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestSchemaMinorVersion
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestPrimaryURL
  • mv.impact.acquire.GenICam.TransportLayerControl.gevManifestSecondaryURL

All the features above might be accessible using the mv.impact.acquire.GenICam.DeviceControl.deviceManifestEntrySelector and other manifest table related features in the mv.impact.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.38.0

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

Changed Compile-time Behavior

  • The property mv.impact.acquire.SystemSettings.workerPriority as well as the enumeration mv.impact.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 mv.impact.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 benefits to an application.

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

  • mv.impact.acquire.labs.FirmwareUpdater
    The FirmwareUpdater class has moved from the mv.impact.acquire.labs namespace to mv.impact.acquire.FirmwareUpdater 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.cs. 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

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!

Changed Compile-time Behavior

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

Deprecated Stuff

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:

Porting Existing Code Written With The .NET Framework Version To .NET Standard

When an application has been developed using the .NET Framework version of the Impact Acquire .NET interface and this now shall be migrated to use the .NET Standard version there is really not too much to do. The first thing that must be done obviously is to migrate the application itself to .NET Standard (for libraries) or .NET Core (for applications). Essentially this boils down to recreate project files for the desired target frameworks and is described in various places on the net and therefore out the scope of this documentation. A good starting point might be this page: https://docs.microsoft.com/en-us/dotnet/core/porting/.

Once this has been done 2 more things are needed:

  • reference the .NET Standard builds of the Impact Acquire assemblies instead of the .NET Framework ones
  • make sure that the System.Drawing.Common package for .NET Standard is installed. This is required for allowing the Impact Acquire .NET API to return instances of the System.Drawing.Bitmap class. Refer to Efficiently create System.Drawing.Bitmap instances for details and support information.

The latter requirement is also the sole reason for the Impact Acquire API being bound to the .NET Standard version 2.0 or above as with this version bitmap support was added to the .NET Standard API.

Porting existing code written with the mvIMPACT_NET interface

With the introduction of this interface all code inside the namespace mvIMPACT_NET.acquire in the assembly mvIMPACT_NET.dll which is part of the mvIMPACT-SDK image processing library became obsolete.

The latter implementation provides a couple of advantages:

  • It is fully decoupled from the rest of the mvIMPACT-SDK image processing library thus can be used easily either with third party vendors image processing libraries or with an application either not needing image processing or coming with its own processing algorithms. This significantly reduces the complexity of client installation packages and also reduces the memory footprint of a deployed application
  • It is completely written in C# while the deprecated stuff was written in C++ with managed extensions which is no longer supported by recent versions of Microsoft Visual Studio®
  • It is fully binary compatible with Mono (http://www.mono-project.com) thus an application compiled on Windows® can directly be executed on Linux® as well
  • It finally fixes a couple of issues related to garbage collection that are present in the previous implementation
  • It offers some additional features exclusively for .NET developers (see e.g. all the stuff from the namespace mv.impact.acquire.helper like the class mv.impact.acquire.helper.RequestProvider)
  • It allows direct access to the acquired data without the need to use the mvIMPACT_NET.Image class
  • It allows direct acquisition of data into managed memory (see CaptureToUserMemory.cs)
  • Its now possible to create instances of objects anywhere in the inheritance hierarchy of the mv.impact.acquire namespace while previously an application could only directly create objects from which no other object was derived. So in mvIMPACT_NET.acquire if there was an object A and an object B deriving from A then due to a design flaw it was not possible to create an instance of A on the heap
Note
Please note that also the newer mvIMPACT image processing library has been declared deprecated and is no longer supported so think carefully about porting code from the older to the newer implementation. It might not be worth the effort!

Porting existing applications to use the mv.impact.acquire namespace will not require much work. This section will list the most important differences.

Assembly references

As the new interface is exported from a different assembly, this new assembly must of course also be referenced by the application:

Note
  • The assembly mv.impact.acquire.dll exports the main interface
  • For information about the other assemblies belonging to Impact Acquire have a look at the Building section

Namespaces

All code previously located in the namespace mvIMPACT_NET.acquire in the assembly mvIMPACT_NET.dll is replaced by the namespace mv.impact.acquire in mv.impact.acquire.dll thus using statements must be changed for existing applications. So

using mvIMPACT_NET;
using mvIMPACT_NET.acquire;

becomes

using mvIMPACT_NET;
using mv.impact.acquire;

Of course if only the acquire namespace has been used simply remove ALL the using statements referencing the mvIMPACT_NET assembly and remove the reference to mvIMPACT_NET.dll from your project as well! It is no longer needed then!

The 'ref' keyword

While the previous implementation of the acquisition interface in mvIMPACT_NET.dll did require an explicit use of the 'ref' keyword, the new interface exported by mv.impact.acquire.dll does not, thus e.g. code like this:

Statistics statistics = new Statistics(ref pDev);
FunctionInterface fi = new FunctionInterface(ref pDev);
SystemSettings ss = new SystemSettings(ref pDev);
mv.impact.acquire.FunctionInterface
The function interface to devices supported by this interface.
Definition FunctionInterface.cs:21
mv.impact.acquire.Statistics
Contains statistical information.
Definition Statistics.cs:10
mv.impact.acquire.SystemSettings
A class for accessing general settings that control the overall behaviour of a device driver.
Definition SystemSettings.cs:6

becomes

Statistics statistics = new Statistics(pDev);
FunctionInterface fi = new FunctionInterface(pDev);
SystemSettings ss = new SystemSettings(pDev);

So by simply removing the 'ref' keyword the client code can be compiled again.

The device manager became a static class

The Impact Acquire interface always requires at least one instance of the class mv.impact.acquire.DeviceManager (mvIMPACT_NET.acquire.DeviceManager previously). In the previous implementation this sometimes resulted in either strange behaviour:

  • Whenever the garbage collector noticed that there is no one referencing and using any instance of the device manager and the garbage collector decided to delete all device manager objects this did automatically close ALL devices(including the ones still in use)

or complicated code that made sure at least one device manager was present:

  • Some applications therefore did create an instance of the DeviceManager class a class member and did access that instance during shut-down of the application.

To address this problem this implementation now made mv.impact.acquire.DeviceManager a static class. In an application this requires a small change. Instances of mv.impact.acquire.DeviceManager must no longer be created, but its member functions must be accessed directly:

Previous code probably looked like this:

class Class1
{
[MTAThread]
static void Main(string[] args)
{
devMgr = new mvIMPACT_NET.acquire.DeviceManager();
uint devCnt = devMgr.deviceCount();
// more code
// make sure the device manager is not deleted by the garbage collector too early
devMgr.updateDeviceList();
}
}

Now this can be written in a much shorter way with a defined behaviour that is no longer affected by garbage collection issues:

class Class1
{
[MTAThread]
static void Main(string[] args)
{
uint devCnt = mv.impact.acquire.DeviceManager.deviceCount();
// more code
}
}
mv.impact.acquire.DeviceManager
Grants access to devices that can be operated by this software interface.
Definition DeviceManager.cs:157
mv.impact.acquire.DeviceManager.deviceCount
static int deviceCount
Returns the number of devices currently present in the system.
Definition DeviceManager.cs:1064
mv.impact.acquire
This namespace contains classes and functions belonging to the image acquisition module of this SDK.
Definition Enumerations.cs:2
mv.impact
Definition Enumerations.cs:2
mv
Definition Enumerations.cs:2

Creating mvIMPACT SDK images (mvIMPACT_NET.Image instances)

In case an existing application did not only use image acquisition module of mvIMPACT_NET but the image processing functions as well a slight change when creating image in a mvIMPACT-SDK compatible format is needed.

While previous code did look like this:

// This call is fast, as it uses the request memory to create the IMPACT image. However
// the IMPACT image will become invalid as soon as the request buffer is unlocked via
// fi.imageRequestUnlock( requestNr );
Image image = pRequest.getIMPACTImage(TImpactBufferFlag.ibfUseRequestMemory);
mv.impact.acquire.TImpactBufferFlag
TImpactBufferFlag
Flags to define the way an mvIMPACT buffer is created and handled.
Definition Request.cs:15

After porting the application to use the mv.impact.acquire.dll it will look like this:

// This call is fast, as it uses the request memory to create the IMPACT image. However
// the IMPACT image will become invalid as soon as the request buffer is unlocked via
// fi.imageRequestUnlock( requestNr );
Image image = new Image(pRequest.getIMPACTImage(TImpactBufferFlag.ibfUseRequestMemory));

So the mvIMPACT_NET.Image constructor must be invoked explicitly now, while the previous application did directly return the mvIMPACT_NET.Image instance. This change is one result of the decoupling of the image acquisition related part of the interface from the image processing related one.

Names of functions and properties

Enumerated properties use generics now to define their data types. So e.g. code like this:

SystemSettings ss = new SystemSettings(ref pDev);
PropertyIAcquisitionMode p = ss.acquisitionMode;
mv.impact.acquire.SystemSettings.acquisitionMode
readonly EnumPropertyI< TAcquisitionMode > acquisitionMode
An enumerated integer property defining the acquisition mode of the device.
Definition SystemSettings.cs:65

becomes

SystemSettings ss = new SystemSettings(pDev);
EnumPropertyI<TAcquisitionMode> p = ss.acquisitionMode;
mv.impact.acquire.EnumPropertyI
A template class to represent 32 bit integer properties and 32 bit enumerated integer properties.
Definition EnumPropertyI.cs:61

So each occurrence of

PropertyIxyz

must be replaced by

EnumPropertyI<Txyz>
Note
The same will apply for enumerated 64-bit integer and floating point properties