IltmmCapture::SetPreferredFilter

#include "ltmm.h"

C Syntax

HRESULT IltmmCapture_SetPreferredFilter(pCapture, FilterType, Val)

C++ Syntax

HRESULT SetPreferredFilter(FilterType, Val)

IltmmCapture *pCapture;

pointer to an interface

long FilterType

value for a filter type

BSTR Val;

string

Sets a preferred filter (decoder or demultiplexer.

Parameter

Description

pCapture

Pointer to an IltmmCapture interface.

FilterType

Value that indicates filter type. For a list of possible values, refer to ltmmCapture_PreferredFilter Constants.

Val

String that has the following possible values:

  • Display Name of the filter

  • Friendly Name of the filter

  • ltmmFilter_LEADDefault (this will use the default LEAD filter)

  • ltmmFilter_DontCare (this is the same as setting the value to NULL)

  • NULL (don't use any preferred filter - revert to the default DirectShow filter)

For a list of possible values, refer to ltmmFilter Constants.

Returns

S_OK

The function was successful.

<> S_OK

An error occurred. Refer to the Error Codes or the HRESULT error codes in the DirectShow documentation.

Comments

By default, the toolkit uses filters according to the default DirectShow mechanism, which assigns a merit to each filter. The filters with the highest merits are tried first. If they fail, the filters with a lower merit are tried next until a combination of filters is found that can handle the graph. However, sometimes 3rd party filters get installed on some computers with a high merit and are used instead of the filters you shipped with your application. Unexpected problems can occur if 3rd party filters are not working properly. The SetPreferredFilter method allows you to control which filters are used in your application. You can decide to use a certain decoder, demultiplexer or you can choose to use only the LEAD filters.

In Windows 7 and later, Microsoft introduced a list of preferred filters for handling certain video subtypes. The filters in this preferred list are used by default in all programs even if other DirectShow filters have higher merit and can handle the same subtype. Use this method can be used to override the filters from that list.

DirectShow filters have a friendly name and a display name. The friendly name is easy to remember and is usually the one displayed by GraphEdit or other filter enumeration utilities. However, there can be more than one filter with the same friendly name, so it is safer to use the display name: no two filters can have the same display name.

Display names for software filters have the following format: @device:sw:GUID\GUID.

For example, the LEAD H.264 Decoder has:

friendly name: LEAD H264 Decoder (3.0)

display name: @device:sw:{083863F1-70DE-11D0-BD40-00A0C911CE86}\{E2B7DF25-38C5-11D5-91F6-00104BDB8FF9}.

The display name for a particular filter can be obtained from the "DirectShow Filter List Utility" shipped with the toolkit. See Examples Programs and Demos for Win32/x64 for more details.

If the FilterType argument is equal to ltmmCapture_PreferredFilter_Generic, then the possible values for Filter are: ltmmFilter_LEADDefault or ltmmFilter_DontCare.

If ltmmFilter_LEADDefault is specified, then the LEAD default decoders and demultiplexers will be set for ALL of the values listed in ltmmCapture_PreferredFilter.

If ltmmFilter_DontCare is specified, then the internal list of the preferred filters will be cleared and the DirectShow filter merit determines which filters will be used.

Use the ltmmFilter_XXX constants whenever possible. See ltmmFilter Constants for a list of predefined values.

Required DLLs and Libraries

LTMM

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS Multimedia C API Help
Introduction
Version History
Getting Started
Copyright Notice
Directories
Multimedia Files You Must Include With Your Application (Redistributables)
Frequently Asked Questions
LEADTOOLS Multimedia Features
Add-on Modules
Programming with LEADTOOLS Multimedia
Appendix
LEADTOOLS Licensing