Matrox Imaging Library (MIL) 10 Update 34
Release Notes (milGenTL)
J 2015
(c) Copyright Matrox Electronic Systems Ltd., 1992-2015.
This document outlines what is new with Matrox support for GenTL and explains the current limitations and particularities.
It also presents last-minute information that did not make it into the manual or on-line help. Note that this help file serves to complement your manual. The information found in this file overrides your formally documented material.
Contents
1.1 What’s new in MIL 10 Update 34
2. Supported operating systems
3. Location of examples (in the help file)
The MIL driver for GenTL supports the following standards:
· GenICam™ GenAPI Standard Version 2.4.1.
· GenICam™ GenTL Standard Version 1.4.
The following features are new for this release:
· New API to enumerate installed GenTL producer libraries.
· New M_SYSTEM_GENTL system type.
· New API to access multiple GenICam XML description files.
· New API to enumerate GenTL modules.
· New API to display the feature browser.
· New API to hook a MIL callback to a GenICam feature change.
· New API to announce M_GRAB buffers prior to grabbing.
· Additions to MappInquire()
o New Inquire types:
§ M_GENTL_ PRODUCER_COUNT. Returns a MIL_INT that specifies the number of installed GenTL producer libraries.
§ M_GENTL_PRODUCER_DESCRIPTOR + N. Returns a MIL_TEXT_PTR that points to the Nth GenTL producer libraries’ path and filename.
§ M_GENTL_PRODUCER_DESCRIPTOR_SIZE + N. Returns a MIL_INT that specifies the Nth GenTL producer libraries’ path and filename string length + 1.
· Additions to MsysAlloc()
o New system type: M_SYSTEM_GENTL
o New combination constants for the SystemNum parameter.
§ M_GENTL_PRODUCER(n). Allows targeting the Nth GenTL producer library installed.
o New InitFlags
§ M_MIXED. Targets any transport layer type interfaces.
§ M_CL. Targets Camera Link® type interfaces.
§ M_CLHS. Targets Camera Link HS™ type interfaces.
§ M_CXP. Targets CoaXPress® type interfaces.
§ M_GEV. Targets GigE Vision® type interfaces.
§ M_U3V. Targets USB 3 Vision™ type interfaces.
· Additions to MsysInquire():
o New Inquire type: M_GENTL_INTERFACE_COUNT. Returns a MIL_INT representing the number of GenTL interfaces.
· Additions to MsysControl():
o M_GC_FEATURE_BROWSER: Displays the Matrox feature browser containing the GenTL system and interface XMLs.
§ M_GENTL_SYSTEM. ControlType combination constant: displays the GenTL system XML.
§ M_GENTL_INTERFACE(n). ControlType combination constant: displays the Nth GenTL interface XML.
· New MsysControlFeature() / MsysInquireFeature()
o Same API as MdigControlFeature() / MdigInquireFeature()
o New combination constants for the ControlType parameter:
§ M_GENTL_SYSTEM. Targets the GenTL system XML.
§ M_GENTL_INTERFACE(n). Targets the Nth GenTL interface XML.
o M_FEATURE_ENUM_ENTRY_DISPLAY_NAME + N. Inquires the display name of the specified enumeration entry of the specified feature, where N is the index into the enumerated list. See M_FEATURE_ENUM_ENTRY_NAME in the MIL documentation.
o M_STRING_ARRAY_SIZE(). Specifies that the feature value is expressed as a string of a specified size. The M_STRING_ARRAY_SIZE() macro passes the size of the user-allocated buffer (first passed to the MdigInquireFeature's UserVarPtr parameter). See M_STRING_ARRAY_SIZE() in the MIL documentation.
o M_FEATURE_CHANGE_HOOK. Identifies the specified FeatureName to trigger the M_FEATURE_CHANGE hook callback. You must be hooked to the M_FEATURE_CHANGE hook type using MsysHookFunction().
· Additions to MsysHookFunction():
o M_FEATURE_CHANGE. Hooks the function to the event that occurs when a specified feature changes. The list of potential feature change events is set using MdigControlFeature() with M_FEATURE_CHANGE_HOOK.
§ M_ALL. HookType combination constant. Specifies the M_FEATURE_CHANGE event will get triggered by any feature.
§ M_GENTL_SYSTEM: HookType combination constant. Hooks a feature change callback on the GenTL system XML.
§ M_GENTL_INTERFACE(n): HookType combination constant. Hooks a feature change callback on the Nth GenTL interface XML.
· Additions to MsysGetHookInfo():
o M_GC_FEATURE_CHANGE_NAME: Returns an array of type MIL_TEXT_CHAR that contains the name of the feature that triggered the event. Can only be called for a M_FEATURE_CHANGE hook type.
o M_GC_FEATURE_CHANGE_NAME_SIZE: Returns a MIL_INT that specifies the string length + 1 of the feature name that triggered the event. Can only be called for a M_FEATURE_CHANGE hook type.
· Additions to MdigInquire():
o M_GENTL_INTERFACE_INDEX. Returns a MIL_INT that specifies the index of the GenTL interface associated to this digitizer.
o M_GENTL_STREAM_COUNT. Returns a MIL_INT representing the number of GenTL streams associated to this digitizer.
· Additions to MdigControl():
o M_GC_FEATURE_BROWSER: Displays the Matrox feature browser containing the GenTL device, remote device and stream XMLs.
§ M_GENTL_DEVICE. ControlType combination constant that displays the GenTL device XML.
§ M_GENTL_REMOTE_DEVICE. ControlType combination constant that displays the GenTL remote device (camera) XML.
§ M_GENTL_STREAM(n). ControlType combination constant that displays the Nth GenTL stream XML.
o M_GENTL_ANNOUNCE_BUFFER. With GenTL, buffers must be announced to the GenTL producer before starting the acquisition with MdigGrab(). Note that it is not necessary to announce buffers used with MdigGrabContinuous() or MdigProcess().
§ ControlType: MIL buffer identifier.
o M_GENTL_REVOKE_BUFFER. Revokes a previously announced buffer. Acquisition must be stopped before revoking a buffer.
§ ControlType: MIL buffer identifier of a previously announced buffer.
· Additions to MdigControlFeature() / MdigInquireFeature():
o New combination constants for the ControlType parameter:
§ M_GENTL_DEVICE. Targets the GenTL device’s XML.
§ M_GENTL_REMOTE_DEVICE (Default). Targets the GenTL remote device’s XML (e.g. the camera)
§ M_GENTL_STREAM(n). Targets the Nth GenTL stream’s XML.
o M_FEATURE_ENUM_ENTRY_DISPLAY_NAME + N. Inquires the display name of the specified enumeration entry of the specified feature, where N is the index into the enumerated list. See M_FEATURE_ENUM_ENTRY_NAME in the MIL documentation.
o M_STRING_ARRAY_SIZE(). Specifies that the feature value is expressed as a string of a specified size. The M_STRING_ARRAY_SIZE() macro passes the size of the user-allocated buffer (first passed to the MdigInquireFeature's UserVarPtr parameter). See M_STRING_ARRAY_SIZE() in the MIL documentation.
o M_FEATURE_CHANGE_HOOK. Identifies the specified FeatureName to trigger the M_FEATURE_CHANGE hook callback. You must be hooked to the M_FEATURE_CHANGE hook type using MdigHookFunction().
· Additions to MdigHookFunction():
o M_FEATURE_CHANGE. Hooks the function to the event that occurs when a specified feature changes. The list of potential feature change events is set using MdigControlFeature() with M_FEATURE_CHANGE_HOOK.
§ M_ALL. HookType combination constant. Specifies the M_FEATURE_CHANGE event will get triggered by any feature.
§ M_GENTL_DEVICE: HookType combination constant. Hooks a feature change callback on the GenTL device XML.
§ M_GENTL_REMOTE_DEVICE: HookType combination constant. Hooks a feature change callback on the GenTL remote device (camera) XML.
§ M_GENTL_STREAM(n): HookType combination constant. Hooks a feature change callback on the Nth GenTL stream XML.
· Additions to MdigGetHookInfo():
o M_GC_FEATURE_CHANGE_NAME: Returns an array of type MIL_TEXT_CHAR that contains the name of the feature that triggered the event. Can only be called for a M_FEATURE_CHANGE hook type.
o M_GC_FEATURE_CHANGE_NAME_SIZE: Returns a MIL_INT that is the string length + 1 of the feature name that triggered the event. Can only be called for a M_FEATURE_CHANGE hook type.
· Additions to MbufControl():
o M_GC_FEATURE_BROWSER: Displays the Matrox feature browser containing the GenTL buffer XML.
§ M_GENTL_BUFFER. ControlType combination constant: displays the GenTL buffer XML.
· New MbufControlFeature() / MbufInquireFeature()
o Same API as MdigControlFeature() / MdigInquireFeature()
o Combination constants for the ControlType parameter
§ M_GENTL_BUFFER (default). Targets the GenTL buffer XML.
o M_FEATURE_CHANGE_HOOK. Identifies the specified FeatureName to trigger the M_FEATURE_CHANGE hook callback. You must be hooked to the M_FEATURE_CHANGE hook type using MbufHookFunction().
· Additions to MbufHookFunction():
o M_FEATURE_CHANGE. Hooks the function to the event that occurs when a specified feature changes. The list of potential feature change events is set using MdigControlFeature() with M_FEATURE_CHANGE_HOOK.
§ M_ALL. HookType combination constant. Specifies the M_FEATURE_CHANGE event will get triggered by any feature.
§ M_GENTL_BUFFER: HookType combination constant. Hooks a feature change callback on the GenTL buffer XML.
· Additions to MbufGetHookInfo():
o M_GC_FEATURE_CHANGE_NAME: Returns an array of type MIL_TEXT_CHAR that contains the name of the feature that triggered the event. Can only be called for a M_FEATURE_CHANGE hook type.
o M_GC_FEATURE_CHANGE_NAME_SIZE: Returns a MIL_INT that is the string length + 1 of the feature name that triggered the event. Can only be called for a M_FEATURE_CHANGE hook type.
This section lists all the operating systems that the Matrox GenTL system supports.
· 32/64-bit Windows® 7.
· 32/64-bit Windows® 8.
In the help file, the location information written at the top of examples might not be up-to-date. Use MIL Example Launcher to find an example on disk.
A problem has been found when MIL 10 Processing Pack 1 is installed after MIL10 Update 34 (M10U034). The MIL 10 Processing Pack 1 installer will overwrite MIL import libraries that are provided by MIL 10 Update 34. The following functions will therefore no longer link:
· MsysControlFeature
· MsysInquireFeature
· MbufControlFeature
· MbufInquireFeature
To resolve this issue, re-install M10U034 or make sure to install MIL 10 Processing Pack 1 before installing M10U034.