| Customize Help

DirectShow capture filter for MIL


MIL provides a DirectShow filter (COM object) for grabbing images, called the MIL capture filter. DirectShow is a multimedia framework and API, produced by Microsoft for software developers, to perform various operations with media files or streams. It uses a modular architecture, and each stage of processing is done by a COM object called a filter. A set of filters in DirectShow is called a filter graph. Filters are connected together in the filter graph; filter connection points are COM objects called pins. The MIL capture filter is a source filter that introduces image data captured by a camera into a DirectShow filter graph, where it can then be connected to other DirectShow filters. For example, the following diagram shows a MIL capture filter sending image data to two default DirectShow filters, a File Writer filter, which writes the image data to a file, and a Video Renderer filter, which renders the image data on the computer's monitor.

Installing the MIL capture filter is optional, but it is installed by default. If during the MIL/MIL-Lite installation you chose not to install the MIL capture filter, you must re-install MIL/MIL-Lite if you now require the MIL capture filter. When writing a DirectShow application using the MIL capture filter, you must include the MilDSFCapture.h file in your application.

COM objects expose their methods through one or more interfaces. The interface of the MIL capture filter is called IMilCapture and the interface of its pin object is called IMilCapturePin. A MIL system is allocated internally after a MIL capture filter object is created and added to the filter graph. The MIL capture filter can have two pins, a preview pin and an output pin, for each digitizer possible on your MIL system. A preview pin is generally used to preview the video data on the monitor and the output pin is generally used to process the data. Both pins share the same interface and output the same data. A MIL digitizer is allocated internally when one of the MIL capture filter's pins is connected to another filter's input. If one of the pins is connected to another filter's input, a new pair of pins becomes available for connection.

/* See DirectShow Reference on MSDN for more information on any
   functions and methods used in this example specific to DirectShow. */

IMilCapture*      pMilCapture    = NULL;  /* MIL system DirectShow interface.    */
IMilCapturePin*   pMilCapturePin = NULL;  /* MIL digitizer DirectShow interface. */
IGraphBuilder*    pGraphBuilder  = NULL;  /* DirectShow Graph building utility.  */

HRESULT hr = S_OK; /* HRESULT variable that stores the outcome of an operation */
   
/* Creates a filter graph object to store filters */
hr = CoCreateInstance(  CLSID_FilterGraph,
                        NULL,
                        CLSCTX_INPROC_SERVER,
                        IID_IGraphBuilder,
                        (void**)&pGraphBuilder );

/* Creates the Matrox Capture filter object */
hr = CoCreateInstance(  CLSID_MilCapture,
                        NULL,
                        CLSCTX_INPROC_SERVER,
                        IID_IMilCapture,
                        (void**)&pMilCapture );

/* Set MIL system information before the MIL system is allocated. A MIL 
   system is allocated internally when the filter is added to the filter graph. */
pMilCapture->setSystemInfo( MIL_TEXT("M_SYSTEM_DEFAULT"), M_DEFAULT );
pGraphBuilder->AddFilter( pMilCapture, NULL );

/* Find a pin on the MIL Capture Filter. Only one pin is available when the filter
   is initially added to the filter graph. A new pin is created when the first pin 
   is connected to another filter, only if there are digitizers avalable. */
IPin* pIPin = NULL;
pMilCapture->FindPin( L"default", &pIPin );

/* Queries the IID_IMilCapturePin interface to expose the IMilCapturePin methods. */
hr = pIPin->QueryInterface( IID_IMilCapturePin, (void**)&pMilCapturePin );

IMilCapture interface

The MIL capture filter interface, IMilCapture, contains information and settings about a MIL system, and has much of the functionality of the MIL System module. It inherits methods from the IBaseFilter interface. You can query this interface using IID_IMilCapture. The following table lists methods specific to the IMilCapture interface:

IMilCapture interface methods

Description
HRESULT getAppID(MIL_ID *AppId);

This method inquires the identifier of the current MIL application context. Note that only one application context is allocated for all MIL DirectShow capture filter instances.

The AppId parameter specifies the address of the variable in which to write the current MIL application context identifier.
HRESULT setSystemInfo(MIL_CONST_TEXT_PTR SystemName, MIL_INT DevNum);

This method sets MIL system information in the IMilCapture filter interface, before the system is allocated. This function must be used before allocating the system, which occurs when the filter is added to the IGraphBuilder interface.

The SystemName parameter specifies the type of system to allocate and can be set to the same values as the SystemDescriptor parameter of MsysAlloc().

The DevNum parameter specifies the number (or rank) of the target board of the specified system type and can be set to the same values as the SystemNum parameter of MsysAlloc().
HRESULT sysControl(MIL_INT64 ControlType, MIL_INT ControlValue);

This method controls a specified system setting. Parameter settings are the same as the corresponding parameters of MsysControl().
HRESULT sysGetHookInfo(MIL_ID EventId, MIL_INT64 InquireType, void *UserVarPtr);

This method gets information about the system event that caused the hook-handler function to be called. This should only be called within the scope of a system hook-handler function. Parameter settings are the same as the corresponding parameters of MsysGetHookInfo().
HRESULT sysHookFunction(MIL_INT HookType, MIL_SYS_HOOK_FUNCTION_PTR HookHandlerPtr, void *UserDataPtr);

This method attaches or detaches a hook-handler function to a specified system event. Parameter settings are the same as the corresponding parameters of MsysHookFunction().
HRESULT sysInquire(MIL_INT64 InquireType, void *UserVarPtr);

This method inquires about a specified system setting. Parameter settings are the same as corresponding parameters of MsysInquire().

All methods will return HRESULT value S_OK if successful, or E_FAIL if unsuccessful.

IMilCapturePin interface

The pin interface, IMilCapturePin, contains information and settings about a MIL digitizer, and has much of the functionality of the MIL Digitizer module. It inherits methods from the IPin interface. You can query this interface using IID_IMilCapturePin. The capture filter can have two pins per digitizer possible on your MIL system. The following table lists methods specific to the IMilCapturePin interface:

IMilCapturePin interface methods

Description
HRESULT set_DigitizerInfo(MIL_INT DevNum, MIL_INT64 ChNum, MIL_CONST_TEXT_PTR DcfPath);

This method sets MIL digitizer information in the IMilCapturePin interface, before the digitizer is allocated. A digitizer is allocated only when a pin is connected to another filter. If you do not specify digitizer information, the information will be set to the default values specified during MIL installation.

The DevNum parameter specifies the device number of the digitizer that is required and can be set to the same values as the DigNum parameter of MdigAlloc().

The ChNum parameter specifies the channel on which the digitizer is to acquire data and can be set to the same values as MdigControl() with M_CHANNEL.

The DcfPath parameter specifies the name of the digitizer configuration format (DCF) appropriate for your camera and can be set to the same values as the DataFormat parameter of MdigAlloc().
HRESULT is_DigAllocated();

This method inquires whether a digitizer is allocated. Returns HRESULT value S_OK if the digitizer is allocated and E_FAIL if the digitizer is not allocated.
HRESULT set_CaptureBufferFormatPriority(CAPTURE_BUFFER_FORMAT CbfId, MIL_INT PriorityIndex);

This method sets the order for the list of grab buffer formats that the MIL capture filter tests to determine the format to use to allocate the grab buffer internally. You cannot explicitly specify a data buffer format for images grabbed by the camera when using the MIL capture filter. Instead, the filter determines which buffer format to use before the grab starts. It does this sequentially, by testing each buffer format in a list. If the test fails with the first buffer format, it tests the next buffer format in the list. The grab buffers are allocated with the format of the first buffer format that passes the test. With this method, you can set the order of the list to minimize the amount of testing. When a format changes place in the list, any format that was previously in that position moves down the list. For example, if you want the MONO8 format tested first, you would call the method set_CaptureBufferFormatPriority(CBF_MONO8, 0) on the pin object that you created, and the format that was previously first becomes the second tested format.

The CbfId parameter specifies a possible buffer format and should be set to one of the following values:

Value

Description
CBF_BGR32

Specifies the buffer format as M_BGR32.
CBF_YUV16_YUYV

Specifies the buffer format as M_YUV16_YUYV.
CBF_MONO8

Specifies the buffer format as M_MONO8.

The PriorityIndex parameter sets the position in the list for a grab buffer format and can be set to any value greater than or equal to 0, where 0 specifies the top of the list.
HRESULT get_CaptureBufferFormatAtPriority(MIL_INT PriorityIndex, CAPTURE_BUFFER_FORMAT *CbfId);

This method inquires the grab buffer format at the specified position in the list of grab buffer formats that the MIL capture filter tests to determine the format to use to allocate the grab buffer internally.

The PriorityIndex parameter specifies the position in the list about which to inquire and can be set to any value greater than or equal to 0, where 0 inquires the format at the highest priority.

The CbfId parameter specifies the address in which to write the requested information and can return one of the following values:

Value

Description
CBF_BGR32

Specifies that the buffer format M_BGR32 is at the specified position in the list.
CBF_YUV16_YUYV

Specifies that the buffer format M_YUV16_YUYV is at the specified position in the list.
CBF_MONO8

Specifies that the buffer format M_MONO8 is at the specified position in the list.
HRESULT set_DebugParam(PinDbgParam DebugOptionType, MIL_INT DebugOptionValue);

This method sets pin debugging options.

The DebugOptionType parameter specifies the debugging option to configure and can be set to one of the following values:

Value

Description
PRINT_PIN_FRAME_COUNTER

Specifies the debugging option that overlays the frame counter in the top-left corner of the grabbed image.
PRINT_PIN_TIMESTAMP

Specifies the debugging option that overlays the time stamp in the top-left corner of the grabbed image.

The DebugOptionValue parameter specifies whether to enable or disable the debugging option and can be set to one of the following values:

Value

Description
M_TRUE

Specifies to enable the debugging option.
M_FALSE

Specifies to disable the debugging option.
HRESULT get_DebugParam(PinDbgParam DebugOptionType, MIL_INT* DebugOptionValue);

This method inquires pin debugging options.

The DebugOptionType parameter specifies the debugging option to inquire and can be set to one of the following values:

Value

Description
PRINT_PIN_FRAME_COUNTER

Specifies the debugging option that overlays the frame counter in the top-left corner of the grabbed image.
PRINT_PIN_TIMESTAMP

Specifies the debugging option that overlays the time stamp in the top-left corner of the grabbed image.

The DebugOptionValue parameter specifies the address in which to write the requested information and can return one of the following values:

Value

Description
M_TRUE

Specifies the debugging option is enabled.
M_FALSE

Specifies the debugging option is disabled.
HRESULT set_FIFOSize(MIL_INT FIFOSize);

This method sets the number of grab buffers that the MIL capture filter should allocate; grabbing is performed by an internal call to MdigProcess().

The FIFOSize parameter specifies the number of buffers that the MIL capture filter should allocate.
HRESULT get_FIFOSize(MIL_INT *FIFOSize);

This method inquires the number of grab buffers that the MIL capture filter should allocate for the internal call to MdigProcess().

The FIFOSize parameter specifies the address in which to write the number of buffers that the MIL capture filter should allocate.
HRESULT set_PinMediaSubTypePriority(MEDIASUBTYPE_FORMAT MfId, MIL_INT PriorityIndex);

This method sets the order of the list used to determine the media subtype format of the image data being output by the MIL capture filter. When introducing image data captured by the camera to the DirectShow filter graph, the data is presented as a video media type, with different possible subtypes (see MSDN for more information regarding media types and subtypes). When the MIL capture filter's pin is connected to another filter's input pin, a handshaking occurs between the two pins, and the MIL capture filter tests to see if the filter it has been connected to will accept one of the possible media subtypes it can output. It does this sequentially, by testing each possible media subtype format in the list. If the test fails, it tests the next buffer format in the list. The output will have the same media subtype format as the first format that passes the test. With this method, you can set the order of the list to minimize the amount of testing.

When a format changes place in the list, any format that was previously in that position moves down the list. For example, if you want the RGB32 media subtype format tested first, you would call the method set_PinMediaSubTypePriority(MF_RGB32, 0) on the pin object that you created, and the format that was previously first becomes the second tested format.

The MfId parameter specifies the media subtype format for which to set its order. This parameter can be set to one of the following values:

Value

Description
MF_RGB32

Specifies the RGB32 media subtype format.
MF_YUV16

Specifies the YUY2 media subtype format.

The PriorityIndex parameter sets the position in the list for a media subtype format and can be set to any value greater than or equal to 0, where 0 specifies the top of the list.
HRESULT get_PinMediaSubTypeAtPriority(MIL_INT PriorityIndex, MEDIASUBTYPE_FORMAT *MfId);

This method inquires the media subtype output format at the specified position in the list of media subtype output formats. The list is used to determine the media subtype format of the image data being output by the MIL capture filter.

The PriorityIndex parameter specifies the position in the list for which to inquire the media subtype format. This parameter can be set to any value greater than or equal to 0, where 0 inquires the format at the top of the list.

The MfId parameter specifies the address in which to write the requested information and can return one of the following values:

Value

Description
MF_RGB32

Specifies the RGB32 media subtype format.
MF_YUV16

Specifies the YUY2 media subtype format.
HRESULT digControl(MIL_INT64 ControlType, MIL_DOUBLE ControlValue);

This method controls various digitizer settings. Parameter settings are the same as the corresponding parameters of MdigControl().
HRESULT digControlFeature(MIL_INT64 ControlType, MIL_CONST_TEXT_PTR FeatureName, MIL_INT64 FeatureType, const void *UserVarPtr);

This method controls manufacturer-specific features of the camera. Parameter settings are the same as the corresponding parameters of MdigControlFeature().
HRESULT digGetHookInfo(MIL_ID EventId, MIL_INT64 InfoType, void *UserVarPtr);

This method gets information about a digitizer event that caused the hook-handler function to be called. This should only be called within the scope of a digitizer hook-handler function. Parameter settings are the same as the corresponding parameters of MdigGetHookInfo().
HRESULT digHookFunction(MIL_INT HookType, MIL_DIG_HOOK_FUNCTION_PTR HookHandlerPtr, void *UserDataPtr);

This method attaches or detaches a user-defined hook-handler function to a specified digitizer event. Parameter settings are the same as the corresponding parameters of MdigHookFunction().
HRESULT digInquire(MIL_INT64 InquireType, void *UserVarPtr);

This method inquires various digitizer settings. Parameter settings are the same as the corresponding parameters of MdigInquire().
HRESULT digInquireFeature(MIL_INT64 InquireType, MIL_CONST_TEXT_PTR FeatureName, MIL_INT64 FeatureType, void *UserVarPtr);

This method inquires manufacturer-specific features of the camera. Parameter settings are the same as the corresponding parameters of MdigInquireFeature().

All methods will return HRESULT value S_OK if successful, or E_FAIL if unsuccessful.

For more detailed and up-to-date information about DirectShow, refer to the DirectShow documentation on the MSDN website. For an example of using the DirectShow capture filter, see:

milcapture.cpp