------------------------------------------------------------------------------- Matrox Imaging Library (MIL) 10.0 Release Notes (MIL.net_Dev) December, 2013 (c) Copyright Matrox Electronic Systems Ltd., 1992-2013. ------------------------------------------------------------------------------- The following describes what is new with the latest version of the .NET interface to MIL. It supplements the relevant information included in the MIL User Guide and Command Reference sections on MIL Help. Main table of contents Section 1 : Differences between MIL 10.0 and MIL 9.0 with Update 53 Section 2 : Differences between MIL 9.0 with Update 53 and MIL 9.0 with Update 1 Section 3 : MIL 9.0 Update 1 ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Section 1: Differences between MIL 10.0 and MIL 9.0 with Update 53 Table of Contents for section 1 1. Overview 2. New functionalities and improvements 3. Fixed bugs 4. Known issues ------------------------------------------------------------------------------- 1. Overview - The MIL .NET wrapper is synchronized with MIL 10. This includes new constants, new function overloads and bug fixes. 2. New functionalities and improvements - The MIL.NET wrapper is now compiled against the .NET Framework 4.0 This implies that the assembly Matrox.MatroxImagingLibrary.dll is compatible with Visual Studio 2010 and up. - A new assembly, Matrox.MatroxImagingLibrary.v3.5.dll, compiled against the .NET Framework 3.5 is provided for use with Visual Studio 2008. - Added overloads for backward compatibility with MIL 9. - Added a new function, MdispSelectWPF, to facilitate the integration of MIL displays in a WPF application. - Added an example, MdispWPF, to show how to use the new MdispSelectWPF function. - Deprecated constants now report a warning at compile time. - Deprecated constants will not be visible to Intellisense. 3. Fixed bugs - Fixed the entry point of MgraArgAngle's overload that uses MIL_INT. - Fixed exception throwing that was not enabled properly after the following call sequence. MappAlloc(...) MappControl(..., M_ERROR, M_THROW_EXCEPTION) MappFree(...) MappAlloc(...) MappControl(..., M_ERROR, M_THROW_EXCEPTION) - Fixed Equals(object) implementation for MIL_INT, MIL_UINT and MIL_ID types. - Fixed the IConvertible interface implementation of the MIL_ID, MIL_INT and MIL_UINT types to ensure that they can be converted to their own type. 4. Known issues - When selecting a new buffer of a different size with MdispSelectWPF, the content of the WindowFormsHost is resized to the size of the buffer. This behavior is incorrect and will be changed in an upcoming release. ------------------------------------------------------------------------------- Section 2: Differences between MIL 9.0 with Update 53 and MIL 9.0 with Update 1 Table of Contents for section 2 1. Overview 2. New functionalities and improvements 3. Fixed bugs 4. Additional information 5. Adding to the MIL .NET wrapper ------------------------------------------------------------------------------- 1. Overview - MIL 9 update 53 synchronizes the MIL .NET wrapper with MIL 9 Processing Pack 2, MIL 9 Update 45 and other previous updates. This includes new constants, new function overloads and bug fixes. 2. New functionalities and improvements - Updated Intellisense documentation for public classes. - Added a new MIL_UINT type. - Added a MaxValue and MinValue fields for the MIL_INT and a MIL_UINT types. - Implement IFormattable, IEquatable<T> and IComparable<T> interfaces for MIL_INT, MIL_UINT and MIL_ID types. - Added an overload to MdigAlloc to support passing a string for the DigNum parameter. - Added the implementation of the M_GC_CAMERA_ID macro. - Added overloads for MgraRectAngle and MgraArcAngle. 3. Fixed bugs - Fixed an MdigInquireFeature overload to take a StringBuilder instead of a string for the last parameter. - Fix a bug in the MILExceptionHandler.Manage() function. The delegate would get garbage collected if the method was called twice. - Fix conversion operators for the MIL_INT and MIL_UINT types. - Fix the IConvertible.ToBoolean implementation. Now returns true if value != 0 (instead of value > 0) - Fixed the entry point of a few functions in the Mfunc module. - Fix MappInquire so it can so it can return M_THROW_EXCEPTION when M_ERROR is inquired. - Add an overload for McodeGetResult to get the M_STRING results as an array of 'char' to be used when multiple codes are read. Due to a limitation of the StringBuilder object, the current overload with StringBuilder only returns the first string. - Fix overload for MgraArc in 64-bits: two parameters were of the wrong type - Fix the entry point Specify the correct entry point for MgraRectAngle and MgraArcAngle in x64. 4. Additional information MIL 9 Update 36 updates the documentation which includes a new User Guide chapter on using MIL with .NET. This update contains additional information about how to use MIL in a .NET environment. 5. Adding to the MIL .NET wrapper If functionality required for your application is missing from the MIL .NET wrapper, it is possible to add that functionality to your application until an new version of the MIL .NET wrapper is release. To do so, please refer to the "Adding to the MIL .NET wrapper" application note included with this update. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Section 3: MIL 9 Update 1 Table of Contents for section 3 1. Overview 2. Files installed on the target computer. 3. Requirements 4. Using MIL in a .NET application. 5. Upgrading an existing project. 6. Differences between MIL and MIL for .NET. 7. Language specific notes 8. .NET equivalents of MIL custom data types. 9. Known bugs and limitations ------------------------------------------------------------------------------- 1. Overview This update provides a convenient method for using MIL in a .NET application. Using Microsoft's Platform Invoke technology, this update exposes the Matrox Imaging Library's functionally to .NET languages such as C# and Visual Basic .NET. The goal of this update is to provide .NET programmers with a MIL programming experience as close as possible to MIL programming with C/C++. 2. Files installed on the target computer. This update installs the following new files in Matrox Imaging\MIL\MIL.NET directory. - Matrox.MatroxImagingLibrary.dll // The Interop assembly for using // MIL in .NET - Matrox.MatroxImagingLibrary.xml // xml file for Intellisense support // in Visual Studio. If necessary, the following files in your Matrox Imaging\Tools directory will be updated. - milconfig.exe // An updated version of the milconfig tool - ExampleLauncher.exe // An updated version of the Example Launcher New examples for C# and Visual Basic .NET languages. - C# examples in the "Examples\Examples C#" directory. - Visual Basic .NET examples in the "Examples\Examples VB" directory. 3. Requirements This update has been built against the .NET framework 2.0 Runtime. Therefore, the Matrox.MatroxImagingLibrary.dll assembly supports Visual Studio 2005 and Visual Studio 2008. Visual Studio .NET 2003 is not supported by this update. Notes: Windows XP users must have at least Visual Studio 2005 with Service Pack 1. Windows Vista users must have at least Visual Studio 2005 Service Pack 1 and Visual Studio 2005 Service Pack 1 Update for Windows Vista. 4. Using MIL in a .NET application. This section gives the basic steps to use MIL in a .NET application. 1. Add a reference to the Matrox.MatroxImagingLibrary.dll assembly to your project. a. In Visual Studio, from the Project menu, select Add Reference... b. In the Add Reference dialog, select the Browse tab. c. Go to the Matrox Imaging\MIL\MIL.NET directory, select Matrox.MatroxImaginglibrary.dll and click OK to add the reference. 2. Add the following using directive to your code to import the types in the Matrox.MatroxImagingLibrary namespace. a. Visual C# using Matrox.MatroxImagingLibrary; b. Visual Basic .NET Imports Matrox.MatroxImagingLibrary 3. Add MIL code in your application. 5. Upgrading an existing application To upgrade an existing application with a new version of the Matrox.MatroxImagingLibrary assembly, you must open your project, rebuild the application and re-deploy it. This is necessary because Matrox.MatroxImagingLibrary.dll file is copied to your application's directory when the application is built. Therefore, installing a new version of Matrox.MatroxImagingLibrary.dll won't upgrade existing applications without rebuilding them. ------------------------------------------------------------------------------- IMPORTANT NOTE ------------------------------------------------------------------------------- The following note applies to users who have already installed a version of the MIL 9 Update for .NET development that precedes build 1527. ------------------------------------------------------------------------------- The location of the assembly Matrox.MatroxImagingLibrary.dll has changed as of Build 1527 of the Early Access version of this update. The assembly is no longer in the Matrox Imaging\Tools folder, it is now located in the Matrox Imaging\MIL\MIL.NET folder. To update your project, follow these steps to change the reference to Matrox.MatroxImagingLibrary. 1. Open your project. 2. From the Solution Explorer, expand the References folder. 3. Select Matrox.MatroxImagingLibrary and remove the reference by pressing the delete key or by right-clicking and select Remove. 4. Follow the steps in section 4 of this readme file to add a new reference to Matrox.MatroxImagingLibrary 5. Rebuild your application. NOTE : By default, Visual Basic users may not see the References folder in the solution explorer as explained in step 2. To make it visible, go to the Project menu and select Show All Files or click on the 'Show All Files' icon in the Solution Explorer. ------------------------------------------------------------------------------- 6. Differences between MIL and MIL for .NET. This section outlines the main differences the when using MIL in a .NET application All the MIL functions and constants are static members of the MIL class. Therefore, you must specify the name of the class and the name of the function/constant like in the following example. MIL.MdigControl(DigitizerID, MIL.M_GRAB_MODE, MIL.M_ASYNCHRONOUS); - MIL Errors can be thrown as .NET exceptions. To enable this feature, add the following call after your call to MappAlloc. MIL.MappControl(MIL.M_ERROR, MIL.M_THROW_EXCEPTION) - The MIL_ID type is a structure that implements implicit conversion operators for the int, long and IntPtr types. - A MIL_INT type is a structure provided to enable writing portable code for 32-bits and 64-bits applications. - The MIL_INT type implements explicit conversion operators for the basic .NET types. - Functions that expect a void * in C++ have been overloaded to accept a reference to each supported data type. - Functions that return an array have been overloaded to accept an array of each supported data types. Use the proper data type, as specified in your MIL documentation. - Hook functions are implemented using delegates and User data for hooked functions must be pinned before passing it to the hook function. Please take a look at the MDigProcess example to learn more. - The memory passed to the MbufCreate...() like functions must be pinned to unsure that the memory will not be moved by the garbage collector. - Function that return strings in C++ expect to get a StringBuilder object in .NET - The Mfunc api will not be able to execute a custom MIL function in a specified dll with a specified function name if the dll is a managed assembly. To use a MIL custom function in such a way, the function must be implemented in C/C++ in an unmanaged dll. - MIL macros are implemented as functions. 7. Language specific notes. 1. Visual Basic .NET The MIL.M_NULL value must be casted to a IntPtr when passed to a function that is overloaded to accept a MIL_ID passed by reference or a IntPtr. This is required to force the Visual Basic compiler to use the IntPtr overload of the function. Otherwise, the Visual Basic compiler will create a new instance of a MIL_ID object and pass the new object's reference to MIL. This will result in a MIL_ID leak and a MIL error reporting that a system still has objects associated with it. It could also result in functions reporting errors stating that a particular parameter must be set to M_NULL. Example MIL.MappAllocDefault(MilApplication, MilSystem, MilDisplay, MilDigitizer, CType(MIL.M_NULL, IntPtr)) 8. .NET equivalents of MIL custom data types. MIL Custom type .NET type (32-bits) .NET type (64-bits) MIL_ID MIL_ID MIL_ID MIL_INT MIL_INT MIL_INT MIL_UINT System.UInt32 System.UInt64 MIL_DOUBLE System.Double System.Double MIL_INT8 System.SByte System.SByte MIL_UINT8 System.Byte System.Byte MIL_INT16 System.Int16 System.Int16 MIL_UINT16 System.UInt16 System.UInt16 MIL_INT32 System.Int32 System.Int32 MIL_UINT32 System.UInt32 System.UInt32 MIL_INT64 System.Int64 System.Int64 MIL_UINT64 System.UInt64 System.UInt64 MIL_TEXT_PTR System.String System.String The MIL_TEXT macro has no .NET equivalent and must not be used. The M_PTR_TO_DOUBLE macro has no .NET equivalent and must not me used. 9. Known bugs and limitations. 1. Limitations - This update includes functionality available as of MIL 9 Processing Pack 1. It does not include functionality contained in other processing packs or other updates to MIL 9, even if you have such updates or processing packs installed on your computer. - Using Processing Pack 1 functionality requires that you have MIL 9 Processing Pack 1 installed on your computer. Always refer to your MIL documentation to know if a feature is supported or not. - The solution with all the examples (C# and VB), includes the M3dmap and MCol examples. Theses examples require Processing Pack 1 to run properly. If you compile them and try to run them without Processing Pack 1 you will receive the following error at runtime : Unable to load DLL 'mil<module name>.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E) - The examples provided with this update are for Visual Studio 2005. Visual Studio 2008 users will be asked to upgrade the solution and project files to the new format when they open the examples with Visual Studio 2008.