LEADTOOLS Multimedia (Leadtools.Multimedia assembly) Send comments on this topic. | Back to Introduction | Help Version 17.0.3.22
SetPreferredFilter Method
See Also 
Leadtools.Multimedia Namespace > PlayCtrl Class : SetPreferredFilter Method



filterType
A PreferredFilter enumeration value specifying the desired filter type
val
String with the following possible values:
  • Display Name of the filter
  • Friendly Name of the filter
  • PreferredFilters.LEADDefault (this will use the default LEAD filter)
  • PreferredFilters.DontCare (this is the same as setting the value to NULL)
  • NULL (don't use any preferred filter - revert to the default DirectShow filter)
filterType
A PreferredFilter enumeration value specifying the desired filter type
val
String with the following possible values:
  • Display Name of the filter
  • Friendly Name of the filter
  • PreferredFilters.LEADDefault (this will use the default LEAD filter)
  • PreferredFilters.DontCare (this is the same as setting the value to NULL)
  • NULL (don't use any preferred filter - revert to the default DirectShow filter)
Sets a preferred filter (decoder or demultiplexer)

Syntax

Visual Basic (Declaration) 
Public Overridable Sub SetPreferredFilter( _
   ByVal filterType As PreferredFilter, _
   ByVal val As String _
)
Visual Basic (Usage)Copy Code
Dim instance As PlayCtrl
Dim filterType As PreferredFilter
Dim val As String
 
instance.SetPreferredFilter(filterType, val)
C# 
public virtual void SetPreferredFilter( 
   PreferredFilter filterType,
   string val
)
C++/CLI 
public:
virtual void SetPreferredFilter( 
   PreferredFilter filterType,
   String^ val
)

Parameters

filterType
A PreferredFilter enumeration value specifying the desired filter type
val
String with the following possible values:
  • Display Name of the filter
  • Friendly Name of the filter
  • PreferredFilters.LEADDefault (this will use the default LEAD filter)
  • PreferredFilters.DontCare (this is the same as setting the value to NULL)
  • NULL (don't use any preferred filter - revert to the default DirectShow filter)

Example

Visual BasicCopy Code
Public _result As Boolean = False
Public _form As PlayCtrlForm = New PlayCtrlForm()
Public Sub PlayerPreferredFiltersExample()
    Try
        ' reference the forms capture control
        Dim playctrl As PlayCtrl = _form.PlayCtrl

        ' set the preferred mpeg2 decoder to the LEAD default (which is the LEAD MPEG2 Decoder)
        playctrl.SetPreferredFilter(PreferredFilter.MPEG2Decompressor, Leadtools.Multimedia.Constants.PreferredFilters.LEADDefault)

        ' the default mpeg2 decoder should be the LEAD MPEG2 decoder now
        ' the filter names are not case sensitive, so do ignore the case in the compare
        _result = (String.Compare(playctrl.GetPreferredFilter(PreferredFilter.MPEG2Decompressor), Leadtools.Multimedia.Constants.PreferredFilters.MPEG2Decompressor, True) = 0)
    Catch e1 As Exception
        _result = False
    End Try
End Sub
C#Copy Code
public bool _result = false;
public PlayCtrlForm _form = new PlayCtrlForm();
public void PlayerPreferredFiltersExample()
{
   PlayCtrl playctrl = _form.PlayCtrl;

   try
   {
      // set the preferred mpeg2 decoder to the LEAD default (which is the LEAD MPEG2 Decoder)
      playctrl.SetPreferredFilter(PreferredFilter.MPEG2Decompressor, Constants.PreferredFilters.LEADDefault);

      // the default mpeg2 decoder should be the LEAD MPEG2 decoder now
      // the filter names are not case sensitive, so do ignore the case in the compare
      _result = (string.Compare(playctrl.GetPreferredFilter(PreferredFilter.MPEG2Decompressor), Constants.PreferredFilters.MPEG2Decompressor, true) == 0);
   }
   catch (Exception)
   {
      _result = false;
   }
}

Remarks

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. And unexpected problems can occur if these 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.

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

val is a string for the Display Name or Friendly Name of the filter. If Friendly Name is used, this function will choose the first filter it finds with the specified friendly name.

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

For example Microsoft’s MPEG-2 Splitter has:

friendly name: MPEG-2 Splitter

display name: @device:sw:{083863F1-70DE-11D0-BD40-00A0C911CE86}\{3AE86B20-7BE8-11D1-ABE6-00A0C905F375}

The display name for a particular filter can be obtained from the "DirectShow Filter List Utility" (ltmmListFilters.exe) shipped with the toolkit. See Examples Programs and Demos for Win32/x64 in the Multimedia API help file for more details.

If the filterType parameter is equal to PreferredFilter.Generic, then the filterName parameter's possible values are: PreferredFilters.LEADDefault or PreferredFilters.DontCare. If PreferredFilters.LEADDefault is specified, then default decoders and demultiplexers will be set for all values listed in PreferredFilter. If PreferredFilters.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.

It is recommended that you use the constants from Constants.PreferredFilters whenever possible.

Requirements

Target Platforms: Microsoft .NET Framework 2.0, Windows 2000, Windows XP, Windows Server 2003 family, Windows Server 2008 family, Windows Vista, Windows 7

See Also