Porting Existing Code

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

Warning

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.

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

• 'mvPropHandling.h' is no longer required for the user. An application only needs to link or load the 'mvDeviceManager' library now. The direct dependency between user application and mvPropHandling-lib has been removed.
• The only file the user needs to include is the mvDeviceManager.h now.

Porting Existing Code Written With Versions Smaller Than 1.4.0

The string property 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 corresponding functions of the 'C' API:

TDMR_ERROR DMR_CALL DMR_CreateUserDataEntry( HDEV hDev, HLIST* pEntry );
TDMR_ERROR DMR_CALL DMR_DeleteUserDataEntry( HDEV hDev, HLIST pEntry );
TDMR_ERROR DMR_CALL DMR_WriteUserDataToHardware( HDEV hDev );

The user data access however is still bound to the device list itself. To gain access to the list handling the user data use the handle returned by the function DMR_GetDevice():

Example

HDMR deviceList = INVALID_ID;
HDRV driverRoot = INVALID_ID;
HDEV device = INVALID_ID;
TDMR_ERROR result = DMR_NO_ERROR;
 
if( ( result = DMR_Init( &deviceList ) ) != DMR_NO_ERROR )
{
  printf( "DMR_Init failed (code: %d)\n", result );
  END_APPLICATION;
}
 
if( ( result = DMR_GetDevice( &device, dmdsmSerial, "*", 0, '*' ) ) != DMR_NO_ERROR )
{
  printf( "DMR_GetDevice failed (code: %d)\n", result );
  printf( "DMR_Close: %d\n", DMR_Close() );
  END_APPLICATION;
}
 
HLIST hUserDataList
if( ( result = OBJ_GetHandleEx( device, "UserData", &hUserDataList, 0, 1 ) ) == DMR_NO_ERROR )
{
  printf( "user data not supported for this device.\n" );
}

Porting Existing Code Written With Versions Smaller Than 1.5.0

The mvBlueFOX specific property USBRetransmit in the statistics list has been renamed to USBRetransmitCount.

Porting Existing Code Written With Versions Smaller Than 1.6.0

Deprecated Stuff

• The function DMR_GetImageRequestInfo() has been declared deprecated. It still can be used but new features will only be available via the new function DMR_GetImageRequestInfoEx().
• The function DMR_GetImageRequestResult() has been declared deprecated. It still can be used but new features will only be available via the new function DMR_GetImageRequestResultEx().

Warning

When using the new function make sure that the drivers delivered with the application are up to date as otherwise they might not contain the new function, which will result in the application not to be executable.

Porting Existing Code Written With Versions Smaller Than 1.7.0

Frame Grabber

The value types of the sync. Output related properties available for mvTITAN-G1, mvTITAN-RGB and mvGAMMA-G devices have been changed from 'int' to 'double'. Affected properties are:

• "LowPart_pc" in the corresponding sublist for each pin under 'SyncOutputs' in the devices IOSubSystems sublist (obtained by a call to DMR_FindList() with dmltIOSubSystem
• "Frequency_Hz" in the corresponding sublist for each pin under 'SyncOutputs' in the devices IOSubSystems sublist (obtained by a call to DMR_FindList() with dmltIOSubSystem

Warning

This is a code breaking change! When these properties have been used in a project and either OBJ_GetI() or OBJ_SetI() have been called with handles to any of these properties, these calls MUST be replaced with calls to OBJ_GetF() and OBJ_SetF() when shipping the application with a version newer of 1.6.1 of the device driver.

mvBlueFOX

In very rare cases the introduction of the new property FlashToExposeDelay_us might influence the behavior of existing applications. This property is mainly provided for compatibility reasons. Previous versions of the mvBlueFOX driver produced a fixed delay of about 300 us between the beginning of the flash signal creation and the beginning of the sensors expose period. Newer versions of the driver does NOT produce this delay anymore, which might cause a different illumination for applications using very intensive, short flash and expose times. Applications relying on the delay introduced in older driver versions should set this property to '300' by calling OBJ_SetI().

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 functions and data types that have been removed and their replacement:

• bwbrErrorToDark.
  Use bwbrErrorTooDark instead.
• bwbrErrorToBright.
  Use bwbrErrorTooBright instead.
• urNothing.
  Use urNoUpdatePerformed instead.
• DEV_REQUEST_CANT_UNLOCKED.
  Use DEV_REQUEST_CANT_BE_UNLOCKED instead.
• rrSnapAborted.
  Use rrRequestAborted instead.
• rrScanStandardNotSupported, rrScanRateInvalid, rrCameraUserAOINotSupported. These results have been returned as part of the image request signaled by DMR_ImageRequestWaitFor(). However the error can be checked when requesting the image by calling DMR_ImageRequestSingle(), thus much earlier. Now this function will therefor return DMR_CAMERA_DESCRIPTION_INVALID_PARAMETER when the user tries to request an image with invalid parameters. It' therefore important to check the return value of the DMR_ImageRequestSingle().
• DMR_SetFilterImageBuffer(), DMR_GetFilterImageBuffer(). There is NO direct replacement for these functions, but they haven't done anything anyway. Simply remove all references to these functions.
• The enums TContinuousWhiteBalanceMode, TFilterType and TTapSortMode have been removed from the interface. There is NO direct replacement for these data types, but they haven't been used anywhere. Simply remove all references.

Changed Run-time Behavior

• The property FrameDelay_ms for mvVirtualDevice instances has been renamed to FrameDelay_us. This might break existing binaries!

Porting Existing Code Written With Versions Smaller Than 1.12.0

Changed Compile-time Behavior

The release of 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 functions and data types that have been removed and their replacement:

• DMR_GetImpactRequestBuffer().
  Use DMR_GetImpactRequestBufferEx() instead.
• DMR_GetImageRequestInfo().
  Use DMR_GetImageRequestInfoEx() instead.
• DMR_GetImageRequestResult().
  Use DMR_GetImageRequestResultEx() instead.
• OBJ_GetSFormatted().
  Use OBJ_GetSFormattedEx() instead.
• OBJ_GetSArrayFormatted().
  Use OBJ_GetSArrayFormattedEx() instead.

Changed Run-time Behavior

• Request objects 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

Changed Compile-time Behavior

The release of 2.0.0 of the Impact Acquire interface will 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 functions and data types that have been removed and their replacement:

• TBlueLYNXVideoOutMode has been removed as it was not used anywhere in the code. Remove every occurrence of this data type from your code.
• DMR_GetDeviceInfo().
  Use DMR_GetDeviceInfoEx() instead.
• DMR_SaveSystemToDefault()
  Since version 1.12.58 all features from the 'system settings' list will also be stored/restored by the functions DMR_LoadSetting(), DMR_LoadSettingFromDefault(), DMR_SaveSetting() and DMR_SaveSettingToDefault(), thus using the explicit call to DMR_SaveSystemToDefault() is no longer needed.
• mvDispSetWindow
  Use mvDispSetImage() instead.
• mvDestroyImageWindow
  Use mvDispWindowDestroy() instead.
• mvGetDisplayWindowHWnd
  Use mvDispWindowGetWindowHandle() instead.
• mvGetDisplayStructure
  Use mvDispWindowGetDisplayHandle() instead.
• mvInitDisplayWindow
  Use mvDispWindowCreate() instead.
• mvSetDisplayWindowRefreshTime
  Use mvDispWindowSetRefreshTime() instead.
• mvShowDisplayWindow
  Use mvDispWindowShow instead.
• mvInstallPreProcHandler()
  Use mvDispWindowSetMessageHandler() instead.

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 functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

• dilGeneric.
  When you still need this call OBJ_SetS("Generic") instead of OBJ_SetI(dilGeneric).

Porting Existing Code Written With Versions Smaller Than 2.10.0

Functions and data types 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 functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

• TImageResultConfiguration.
  Use TBoolean instead.

Porting Existing Code Written With Versions Smaller Than 2.15.0

Functions and data types 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 functions and data types that have been removed and their replacement:

Changed Compile-time Behavior

• cfUserAllocatedMemory.
  
• PROPHANDLING_NO_USER_ALLOCATED_MEMORY.
  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 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.19.0

Deprecated Stuff

• The function OBJ_DeleteSetting() has been declared deprecated. Use DMR_DeleteSetting() instead.
• The function OBJ_IsSettingAvailable() has been declared deprecated. Use DMR_IsSettingAvailable() instead.

Porting Existing Code Written With Versions Smaller Than 2.37.0

Functions 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 functions and data types that have been removed and their replacement:

• DMR_SaveSystemToDefault(). As since quite some time now (1.12.58) Impact Acquire stores these settings together with the capture setting calling these function is no longer needed. Simply remove all references.
• DMR_UpgradeDeviceFeatures(). There is NO direct replacement as the function did not perform anything useful anyway. Simply remove all references to this function.

Porting Existing Code Written With Versions Smaller Than 2.38.0

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

Changed Compile-time Behavior

• The enumeration TThreadPriority has been removed from the public interface. Existing binaries will not be affected. An application can continue to use the WorkerPriority property however this is strongly discouraged! Modifying this property does not provide any benefits to an application.

Porting Existing Code Written With Versions Smaller Than 2.47.0

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

Changed Compile-time Behavior

• DMR_EventWaitFor(), DMR_EventGetData() and EventData. Use OBJ_CreateCallback(), OBJ_DeleteCallback(), OBJ_AttachCallback() and OBJ_DetachCallback() instead.
  An example can be found in Callback.c. To wait for events of type ::detPnPArrival and ::detPnPRemoval register a callback for the property State to wait for an event of type ::detFrameStart a callback for the event result of this event can be registered after the event has been configured to get notified.

Changed Run-time Behavior

All internal code for DMR_EventWaitFor(), DMR_EventGetData() and EventData has been removed from Impact Acquire. Therefore applications that did use these API functions must be recompiled and linked before they can be operated with 5Impact Acquire 2.47.0 or newer.

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 functions and data types that have been removed and their replacement:

• OBJ_DeleteSetting()
  Use DMR_DeleteSetting() instead.
• DMR_GetDeviceInfo().
  Use DMR_GetDeviceInfoEx() instead.
• OBJ_GetHandle()
  Use OBJ_GetHandleEx() instead.
• OBJ_IsSettingAvailable()
  Use DMR_IsSettingAvailable() instead.

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 these functions and data types!

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

• TAcquisitionField
• TCameraDataFormat
• TCameraExternalSyncEdge
• TCameraExternalSyncOutput
• TCameraInterlacedType
• TCameraLinkDataValidMode
• TCameraOutput
• TCameraSerialPortBaudRate
• TClampMode
• TDeviceImageTrigger
• TDigitalOutputControlMode
• TDigitalSignal
• TFieldGateMode
• TInterlacedMode
• TLineCounter
• TOnBoardMemoryMode
• TScanClock
• TScanStandard
• DMR_CopyCameraDescription(), DMR_ExportCameraDescription() and DMR_ImportCameraDescription(). There is NO direct replacement for these functions! Support for frame grabber boards has ended years ago. Simply remove all references to these functions and adjust your code to continue to work without them or stick to older releases of this SDK.

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!