Matrox Imaging Library (MIL) 10 Update 76
Release Notes (milClarityUHD)
June 2018
(c) Copyright Matrox Electronic Systems Ltd., 1992-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.4 Additions to the command reference
1.1.5 Known limitations and particularities
1.2 What’s new in MIL 10 Update 36
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)
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.
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 |
6 x 1080p60 streams |
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 |
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 |
· 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). |
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. |
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. |
Analog connector 1 |
||
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.
· 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.
· 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.
· 64-bit Windows® 7.
· 64-bit Windows® 10.
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.