Matrox Imaging Library (MIL) 10 Update 76

Release Notes (milClarityUHD)

June 2018

This document outlines what is new regarding MIL support for the Matrox Clarity UHD 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. MIL Driver for Matrox Clarity UHD

1.1 What’s new in MIL 10 Update 76

1.1.1 Summary of new features

1.1.2 Grabbing capabilities

1.1.3 Encoding capabilities

1.1.4 Additions to the command reference

1.1.5 Known limitations and particularities

1.1.6 Bug fixes

1.2 What’s new in MIL 10 Update 36

1.2.1 Summary of new features

1.2.2 Additions to the command reference

1.2.3 Known limitations and particularities

2. Supported operating systems

3. Location of examples (in the help file)

1. MIL Driver for Matrox Clarity UHD

1.1 What’s new in MIL 10 Update 76

Note that MIL 10 Update 76 is a cumulative update, including all content from MIL 10 Update 36.

For MIL 10 Update 76, the MILHelp no longer has PDF CHMs for Matrox Clarity UHD. This information has either been integrated into the actual MILHelp, or is contained in this release note.

1.1.1 Summary of new features

Added support of hardware H.264 encoding using the Mseq API and Matrox DirectShow filters.
Added support of grabbing in YUV 4:2:0 and YUV 4:4:4 pixel formats.
Updated MultiCameraDisplay example to add encoding features and support of new pixel formats.
Updated Matrox DirectShow filters to support encoding (see MilEncodeDecode example)

1.1.2 Grabbing capabilities

The MIL Driver for Matrox Clarity UHD supports the following grab buffer pixel formats. Note that if you allocate a grab buffer with an M_DYNAMIC attribute, you must specify the format in which to convert and store the input data using MdigControl with M_PFNC_TARGET_FORMAT, prior to grabbing into the buffer. You can then change the format between grabs. A buffer with an M_DYNAMIC attribute cannot be used with most other MIL functions. You can, however, access the data using MbufInquire with M_HOST_ADDRESS and then process the data directly with a custom function. You can also use the buffer with the MIL Sequence module (Mseq).

MIL grab buffer pixel format	MdigControl with M_PFNC_TARGET_FORMAT	Description
1 band 8-bit		Monochrome 8-bit
M_YUV16 + M_PACKED		YUV 4:2:2 8-bit
M_YUV24 + M_PLANAR		YUV 4:4:4 8-bit planar
RGB 3 band 8-bit		RGB 8-bit planar
M_BGR32 + M_PACKED		BGR32 8-bit packed buffer
M_DYNAMIC	PFNC_BGRa10p	10-bit color depth with a BGRa format. This format is not supported when grabbing from a 3840x2160@50Hz source or higher.
M_DYNAMIC	PFNC_YCbCr411_8	YUV 4:2:0 8-bit
M_DYNAMIC	PFNC_YCbCr422_10p	YUV 4:2:2 10-bit packed (V210 format)

This table represents the maximum number of streams that can be grabbed and displayed depending on the stream resolution, frame rate and the destination buffer pixel format.

Buffer pixel format	Maximum number of streams that can be grabbed and displayed
Monochrome 8-bit	4 x 2160p60 streams and 4 x 1080p60 streams or
	6 x 2160p30 streams and 2 x 1080p60 streams or
	8 x 1080p60 streams
YUV 4:2:0 8-bit	4 x 2160p60 streams or
	6 x 2160p30 streams and 2 x 1080p60 streams or
	8 x 1080p60 streams
YUV 4:2:2 8-bit	3 x 2160p60 streams or
	6 x 2160p30 streams or
	8 x 1080p60 streams
YUV 4:2:2 10-bit	2 x 2160p60 streams and one 1080p60 stream or
	4 x 2160p30 streams and one 1080p60 stream or
	8 x 1080p60 streams
RGB 8-bit planar	2 x 2160p60 streams or
	4 x 2160p30 streams or
	8 x 1080p60 streams
BGR32 8-bit packed	one 2160p60 stream and 2 x 1080p60 streams or
	3 x 2160p30 streams or
	6 x 1080p60 streams
RGB 10-bit packed	3 x 2160p30 streams or
RGB 10-bit packed	6 x 1080p60 streams

1.1.3 Encoding capabilities

This table represents the maximum number of streams that can be simultaneously grabbed, displayed and encoded depending on the stream resolution and frame rate and the destination buffer pixel format.

Buffer pixel format	Encoding profile (MseqControl with M_STREAM_PROFILE) (using default encoding settings)	Maximum number of streams that can be grabbed, displayed and encoded.
Monochrome 8-bit	M_PROFILE_HIGH Buffer is internally converted to YUV 4:2:0 before encoding	one 2160p60 stream or
		3 x 2160p30 streams or
		6 x 1080p60 streams
YUV 4:2:0 8-bit	M_PROFILE_HIGH	2 x 2160p60 streams or
		4 x 2160p30 streams or
		8 x 1080p60 streams
YUV 4:2:2 8-bit	M_PROFILE_HIGH422	one 2160p60 stream or
		3 x 2160p30 streams or
		6 x 1080p60 streams
YUV 4:2:2 10-bit	M_PROFILE_HIGH422 (encoding in 10-bit)	one 2160p60 stream or
		2 x 2160p30 streams or
		5 x 1080p60 streams
RGB 8-bit planar	M_PROFILE_HIGH Buffer is internally converted to YUV 4:2:0 before encoding	one 2160p60 stream or
		3 x 2160p30 streams or
		6 x 1080p60 streams
BGR32 8-bit packed	M_PROFILE_HIGH Buffer is internally converted to YUV 4:2:0 before encoding	one 2160p60 stream or
		3 x 2160p30 streams or
		5 x 1080p60 streams
RGB 10-bit packed	M_PROFILE_HIGH Buffer is internally converted to YUV 4:2:0 before encoding	2 x 2160p30 streams or
		5 x 1080p60 streams

1.1.4 Additions to the command reference

· The Mseq functions are now supported on the Matrox Clarity for H.264 encoding. Please refer to the Mseq section in the MIL Help. Differences with the MIL Help are listed in the table below:

MseqAlloc	Parameter InitFlag	Must be set to M_DEFAULT.
MseqControl/ MseqInquire	M_CODEC_TYPE	M_HARDWARE + M_CLARITY_UHD_H264.
	M_STREAM_BIT_RATE	The default value is 15000 kbits/sec.
	M_STREAM_BIT_RATE_MAX	The default value is 30000 kbits/sec.
	M_STREAM_GROUP_OF_PICTURE_SIZE	The default value is 90 frames per group.
	M_STREAM_LEVEL	Additional supported level: M_LEVEL_5_2.
	M_STREAM_PROFILE	Additional supported profiles: § M_AUTOMATIC (default): choose the profile that matches the pixel format of the buffer passed to MseqFeed. § M_PROFILE_EXTENDED § M_PROFILE_HIGH422
MseqFeed	Matrox Clarity UHD supports encoding buffers in multiple buffer formats but some are more efficient then others. The most efficient encoding buffer pixel formats using M_PROFILE_HIGH are: § M_YUV12 + M_PLANAR + M_ON_BOARD or § M_DYNAMIC + M_ON_BOARD with M_PFNC_TARGET_FORMAT set to PFNC_YCbCr411_8 Most efficient encoding buffer pixel formats using M_PROFILE_HIGH422 are: § M_YUV16 + M_PACKED + M_ON_BOARD or § M_DYNAMIC + M_ON_BOARD with M_PFNC_TARGET_FORMAT set to PFNC_YCbCr422_10p Any other mix of buffer formats and profiles are supported but will result in an internal buffer conversion reducing encoding performance.

· Added the following new MdigControl/Inquire() values:

M_PFNC_TARGET_FORMAT		Specifies the buffer PFNC pixel format used when grabbing in a buffer allocated with the M_DYNAMIC attribute.
	PFNC_BGRa10p	Specifies to grab a 10-bit color depth with a BGRa format (B:10,G:10,R:10, A:2).
	PFNC_YCbCr411_8	Specifies to grab an 8-bit color depth with a YUV 4:2:0 format. Note that the actual data is in YUV 4:2:0 (not YUV 4:1:1) because it is not yet defined in the PFNC specification. The data is in 2 planes: one for the luminance and the other for the chrominance.
	PFNC_YCbCr422_10p	Specifies to grab a 10-bit color depth with a V210 format (YUV 4:2:2 10-bit).

1.1.5 Known limitations and particularities

Hardware H.264 encoding is only supported with a specific board model (CLA4GHDSAE).
Some analog component YPbPr cameras might not be properly detected using the autodetect DCF. In this case you must manually specify the DCF in MILConfig or when using MdigAlloc().
Building the MIL examples using Visual Studio 2015 or 2017 also requires the presence of Windows SDK version 8.1, which is installed from the Visual Studio setup.
The MIL update requires a Windows installation that supports device drivers with SHA-2 digital certificates. Consequently, some Windows 7 installations will require that a Windows Monthly Rollup be applied before the MIL update can be installed.
The MIL-Lite license provided by the Clarity UHD and the MIL licenses stored on the board, if there are any, are not visible from a 32-bit application when running on 64-bit Windows. The use of a license dongle will be required for this scenario.

1.1.6 Bug fixes

Upgrading to the latest version of Windows 10 no longer imposes restrictions on uninstalling MIL/MIL-Lite 10.

1.2 What’s new in MIL 10 Update 36

1.2.1 Summary of new features

The following features are new for this release:

· Supports simultaneous acquisition from up to 8 independent input sources. Use MdigAlloc() with M_DEVn to allocate the digitizer associated with the listed connector, where n is the digitizer device number.

Digitizer device #	Connector name	Description
M_DEV0	Mini-HDMI (type C) connector 0	DVI-D and HDMI 2.0 progressive resolutions up to 2160p60 and interlaced resolutions 1080i50, 1080i59.94 and 1080i60.
M_DEV1	Mini-HDMI (type C) connector 1
M_DEV2	Mini-HDMI (type C) connector 2	DVI-D and HDMI 1.4 progressive resolutions up to 1920 x 1200 p60 and interlaced resolutions 1080i50, 1080i59.94, and 1080i60.
M_DEV2	Analog connector 0	DVI-A progressive resolutions up to 1920 x 1200 p60 and interlaced resolutions (1080i50, 1080i59.94, and 1080i60). SD (analog) resolutions for RS170 (720 x 486 i30), CCIR (720 x 576 i25), NTSC (720 x 486 i30), NTSC/YC (720 x 486 i30), PAL (720 x 576 i25), PAL/YC (720 x 576 i25), NTSC RGB (640 x 480 i30), PAL RGB (768 x 576 i25).
M_DEV3	Mini-HDMI (type C) connector 3	Same as M_DEV2.
M_DEV3	Analog connector 1	Same as M_DEV2.
M_DEV4	Mini Display Port 1.2 connector 0	Display Port 1.2 progressive resolutions up to 2160p60 and interlaced resolutions 1080i50, 1080i59.94 and 1080i60.
M_DEV5	Mini Display Port 1.2 connector 1
M_DEV6	SDI connector 0	Supports grabbing at up to: SD resolutions NTSC (720 x 486 i30) and PAL (720 x 576 i25). HD resolutions (720p50, 720p59.94, 720p60, 1080p23.98, 1080p24, 1080p25, 1080p29.97, 1080p30, 1080p50, 1080p59.94, 1080p60, 1080i50, 1080i59.94, 1080i60). 2K DCI resolutions (2K 23.98p, 2K 24p, 2K 25p). UHD resolutions (2160p23.98, 2160p24, 2160p25, 2160p29.97, 2160p30, 2160p50, 2160p59.94, 2160p60). 4K DCI resolutions (4K 23.98p, 4K 24p, 4K 25p).
M_DEV7	SDI connector 1

· Updated the following MIL hardware-specific examples:

o MdigCrossBar: This example (accessible from the revised ExampleLauncher or located in .\examples\board-specific\MdigCrossBar) implements a crossbar switch, where any video input can be sent to any video output. This example requires a desktop with multiple monitors to view the grabbed images.

o MultiCameraDisplay: This example demonstrates the acquisition capabilities of the Matrox Clarity UHD and how to display grabbed images. It demonstrates:

§ Displaying multiple live streams from multiple boards;

§ No tearing video display;

§ Low latency video display;

§ Live camera addition and removal;

§ Changing the display between windowed and full screen mode;

§ Changing grab buffer pixel formats. Supported pixel formats are: mono8, YUV 4:2:2 8-bit, YUV 4:2:2 10-bit (V210), RGB planar, BGR32 8-bit packed, BGR 10-bit packed;

§ Activating image processing on a live stream;

§ Displaying Matrox Feature Browser so that the user can control the digitizer settings.

1.2.2 Additions to the command reference

· Added support for MbufAlloc1d. Attribute parameter values:

For specifying the intended purpose of the image buffer

M_DYNAMIC

Specifies an image buffer whose bit-depth and data format are specified by the camera (see M_PFNC_TARGET_FORMAT). To determine the required size of the image buffer, use MdigInquire with M_SIZE_X and M_SIZE_Y, respectively. This value can only be used with M_IMAGE and M_GRAB.

Please refer to board-specific example MultiCameraDisplay.

· Added support for MdigControl() with M_GC_FEATURE_BROWSER. Unlike with other Matrox products, when using MdigControl() with M_GC_FEATURE_BROWSER, both the digitizer and system controls are displayed in an interactive dialog box.

· Added support for MsysHookFunction() with M_CAMERA_PRESENT. This hooks the function to the presence of the camera.

· Added the following new MbufControl/Inquire() value:

M_YCBCR_RANGE		Specifies whether the YUV buffer's pixel values are encoded in YCbCr. See the MIL documentation for more information.
	M_DISABLE	Specifies not to encode the YUV buffer's pixel values in YCbCr. This is the default value.
	M_YCBCR_SD	Specifies to encode the YUV buffer's pixel values using the standard-definition YCbCr standard (ITU-R BT.601).
	M_YCBCR_HD	Specifies to encode the YUV buffer's pixel values using the high-definition YCbCr standard (ITU-R BT.709).
	M_YCBCR_UHD	Specifies to encode the YUV buffer's pixel values using the ultra-high-definition YCbCr standard (ITU-R BT.2020). This is new as of MIL 10 Update 36.

· Added the following new MdigControl/Inquire() value:

M_PFNC_TARGET_FORMAT		Specifies the buffer PFNC pixel format used when grabbing in a buffer allocated with the M_DYNAMIC attribute.
	PFNC_BGRa10p	Specifies to grab a 10-bit color depth with a BGRa format (B:10,G:10,R:10, A:2).
	PFNC_YCbCr422_10p	Specifies to grab a 10-bit color depth with a V210 format (YUV 4:2:2 10-bit).

· Added support for grabbing into a native buffer format (allocated using MbufAlloc1d() with M_DYNAMIC) with MdigGrab() and MdigProcess(), please refer to hardware-specific example MultiCameraDisplay.

1.2.3 Known limitations and particularities

· The MIL Driver for Matrox Clarity UHD supports the following grab buffer formats:

§ Monochrome 8-bit;

§ YUV 4:2:2 8-bit;

§ YUV 4:2:2 10-bit (V210) using M_DYNAMIC buffers;

§ RGB planar;

§ BGR32 8-bit packed;

§ BGR 10-bit packed using M_DYNAMIC buffers. This pixel format is not supported when grabbing from a source with a resolution of 3840 x 2160 at 50Hz or higher.

· When grabbing from an SDI source into a monochrome 8-bit or color BGR32 packed buffer, the Matrox Clarity UHD automatically selects the proper color space equations depending on the input resolution (ITU-R BT.601 for SD, ITU-R BT.709 for HD and ITU-R BT.2020 for UHD). When grabbing into a YUV16 packed buffer the input data is not converted. The color space can be inquired using MbufInquire with M_YCBCR_RANGE.

· A maximum of 8 simultaneous grabs from HD sources (1080p60) is supported in YUV16 format.

· A maximum of 2 simultaneous grabs from UHD sources (2160p60) is supported in YUV16 and RGB planar formats except when simultaneously grabbing from digitizer device number 0 and 4 or from digitizer device 1 and 5. A maximum of 1 live grab from an UHD source is supported in a BGR32 packed buffer.

· Supports the RGB 4:4:4 and deep color (10-bit) HDMI colorimetry.

· For the SDI inputs, the following features are not supported:

§ Dual-link;

§ 3D;

§ RGB 4:4:4.

· HDMI inputs are unable to capture from copy-protected HDMI sources (e.g., HDCP).

· On-board H.264 encoding is not supported.

· Windows’ automatic 8.3 file name creation needs to be enabled in order for the MIL installer to access the temp folder when the user name contains a space. This option allows Windows to create short file/folder name aliases for ones with long names for programs, such as the MIL installer, that don't support spaces in the file/folder names. Alternatively, the MIL installer needs to run from a user account that belongs to the administrators group and has no spaces in it. Note that the same applies for uninstalling MIL.

· The required Visual C++ 2017 Redistributable needs the presence of KB2919442 and KB2919355. These will need to be obtained and applied before restarting this update.

· The MdigCrossbar example may or may not work on Windows 10 depending on the PC’s configuration. Please use the new MultiCameraDisplay example.

· MIL/MIL-Lite 10 must NOT be uninstalled if it was installed BEFORE upgrading to the latest version of Windows 10. Failure to do so will corrupt the Windows 10 installation. A fix is coming to remedy the situation.

2. Supported operating systems

· 64-bit Windows® 7.

· 64-bit Windows® 10.

3. Location of examples (in the help file)

In the MIL online help, 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.