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