Matrox Imaging Library (MIL) 10 Update 10
                      Release Notes (MilDirectShowCapture)
                                  June 2014
            (c) Copyright Matrox Electronic Systems Ltd., 1992-2014.

This document outlines what is new with the Matrox Capture filter and
Matrox Sample Grabber filter for Microsoft® DirectShow® and explains its 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 text file serves to complement your manual. The
information found in this file overrides your formally documented material.


1. The Matrox Capture filter for DirectShow®.
   1.1 Differences between MIL 10 Update 10 and MIL 10.
   1.2 What's new in MIL 10 Update 10.
      1.2.1 New features summary
      1.2.2 Bug Fixes
   1.3 What's new in MIL 10.0.
   1.4 What's new in MIL 9.0 Update 46.
   1.5 Known limitations.
2. Supported operating systems.
3. Location of examples (in the help file)


1. The Matrox Capture filter for DirectShow®.

   1.1 Differences between MIL 10 Update 10 and MIL 10.

   - MILDSFCapture.dll now contains 2 different filters:
     * Matrox Sample Grabber filter, to retrieve frames passed between 2 filters.
     * Matrox Capture filter, to grab and interact with MIL systems and digitizers.

   - Improved Matrox Capture filter and pin connections.

   - Renamed MilCaptureDSFilter example.

   - New example for Matrox Sample Grabber filter.

   1.2 What's new in MIL 10 Update 10.

      1.2.1 New feature summary

      - Addition of Matrox Sample Grabber filter.

        The Matrox Sample Grabber filter provides a way to retrieve samples as
        they pass through the filter graph. It is a transform filter with one
        input pin and one output pin. It passes all samples downstream
        unchanged, so you can insert it into a filter graph without altering
        the data stream. Your application can register a callback function
        that will be called every time a sample is received by the filter.
        The main purpose of this filter is to acquire data from almost any
        third-party source using DirectShow® and use the retrieved buffer
        within a MIL application.

        IMilSampleGrabber is the interface class and its GUID (globally unique
        identifier) is IID_IMilSampleGrabber. The filter can be allocated using
        its GUID: CLSID_MilSampleGrabber.
        These are defined in MilDSFCapture.h and MilDSFCaptureGUID.h

        IMilSampleGrabber methods:

        * STDMETHODIMP RegisterCallback(MANAGEDCALLBACKPROC callback, void* UserCallbackData)
            Synopsis: Specifies the callback function to use each time the
                      filter has a MIL buffer available.

               * MANAGEDCALLBACKPROC callback:
                                     Specifies the address of the function that
                                     should be called.

                                     Make sure to use the given MIL_ID only
                                     during the time you are in the
                                     callback-handler, because once the handler
                                     returns, the buffer data is freed.

                                     The callback-handler function must be
                                     declared as follows:

                  void CallbackHandler(
                           MIL_ID bufID,
                           AM_MEDIA_TYPE *pmt,
                           void* userCallbackData
                           bufID:   The MIL_ID that points to the current image.

                           pmt:     Filter connection media type currently in

                           userCallbackData:    User data pointer.

               * void* UserCallbackData:
                       Specifies the address of the user data that you want to
                       make available to the callback-handler function.
                       This address is passed to the callback-handler function
                       through the userCallbackData parameter.
                       Set this parameter to NULL if not used.

      - Added a function to fine-tune the MediaType frame rate value.

        These functions have been added to set the precise frame rate
        to be negotiated.

        * STDMETHODIMP SetSyncFrameRate(BOOL bForce, MIL_DOUBLE fSyncFrameRate)
            Synopsis: Specifies if the filter uses the internally obtained value
                      for the frame rate, or if it uses the specified value in
                      The main purpose of this function is to fix any drift
                      in the audio/video synchronization when generating
                      multimedia files.

               * BOOL bForce:
                      Specifies whether to override the value returned
                      by M_SELECTED_FRAME_RATE
                        - TRUE to use the value in fSyncFrameRate
                        - FALSE to use the internal value obtained with

               * MIL_DOUBLE fSyncFrameRate:
                            Specifies the precise frame rate to use as reference
                            for averageTimePerFrame in CMediaType.
                        - This value is used mostly by the Muxer filters to set
                          the replay frame rate, such as "AVI Mux".

        * BOOL IsForcedSyncFrameRate(MIL_DOUBLE* pfSyncFrameRate)
            Synopsis: Query the forced frame rate if any has been forced.

               * TRUE if a frame rate has previously been forced;
               * FALSE otherwise.

               * MIL_DOUBLE* pfSyncFrameRate:
                             Specify the pointer in which to receive the forced
                             value, if any. If none has been forced, it does not
                             modify the value.
                             If pfSyncFrameRate equals M_NULL, no value will be

      - Renamed MilCaptureDSFilter example.

        MilCaptureDSFilter example is renamed to MilCapture, it is present in
        \Users\Public\Documents\Matrox Imaging\Mil\Examples\DirectShow\MilCapture\
        The example shows how to program with the Matrox Capture filter for
        DirectShow® and give access to MIL systems for external filters.

      - New example for Matrox Sample Grabber filter

        An example of the DirectShow filter named MilSampleGrabber is present in
        \Users\Public\Documents\Matrox Imaging\Mil\Examples\DirectShow\MilSampleGrabber\
        The example shows how to retrieve frames from a third-party
        DirectShow® video source and use it within a MIL application.

      1.2.2 Bug fixes

      - Fixed MediaType structure data to improve precision during
        audio/video synchronization.

      - Fixed MediaSample timestamps if no frame rate value is available.

      - Fixed a problem when loading .grf file in Graphedit, where pins
        would not get reconnected and system could not reallocate properly.

      - Fixed minor memory leaks.

      - Fixed the system selection to be able to save M_DEFAULT instead of the
        actual system set in MilConfig.

      - Added RGB MediaSubType format with positive height to improve
        connection speed.

   1.3 What's new in MIL 10.0.

   - Support for Microsoft® Windows® 8.

   - The filter "Preview" pin has been implemented. A new "Preview" pin is
     allocated for each digitizer available on the selected frame grabber.

   1.4 What's new in MIL 9.0 Update 46.

   - The Matrox Capture filter for DirectShow® supports all video capture
     devices supported by MIL (excluding the Matrox Iris GT).

   - An example of the DirectShow filter named MilCaptureDSFilter is
     present in
     \Users\Public\Documents\Matrox Imaging\Mil\Examples\Board-Specific\DirectShowFilter\MilCapture\
     The example shows how to program with the Matrox Capture for DirectShow®.

   1.5 Known limitations.

   - You can use the following applications with the Matrox Capture filter:
      - AMCap, GraphEdit, Microsoft® DirectShow® API, PlayCap, and VirtualDub.

   - You cannot use VLC media player® with the Matrox Capture filter.

2. Supported operating systems.

   - The Matrox Capture filter is supported on the following editions
     of Microsoft® Windows®:
        XP 32-bit
        7 32-bit
        7 64-bit
        8 32-bit
        8 64-bit

3. Location of examples (in the help file)

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