Microsoft DirectX 8.0 |
This article describes how to use Microsoft® Visual Basic® to manage the components of a filter graph.
This article is written for the Visual Basic developer who is already familiar with application programming in Microsoft® Windows®, Windows-based multimedia programming, and Automation features of the Visual Basic programming system.
This article contains the following sections.
Quartz.dll provides objects that you can use in your Visual Basic-based applications to manage filters and pins. There is an implicit hierarchy among these objects; that is, you must often access the properties of one object to obtain another object. In the following example, an object that appears indented below another indicates that you obtain that lower-level object from a property or method of the higher-level object.
Filter graph object (IMediaControl) Filter collection (RegFilterCollection, FilterCollection properties) Filter Info object (IFilterInfo or IRegFilterInfo in filter collection) Pin collection (Pins property) Pin Info object (IPinInfo item in pins collection)
The top-level object in the hierarchy is the filter graph object, or the IMediaControl object, which represents the entire filter graph. You can access two properties of the IMediaControl object to obtain collections of filter objects. The RegFilterCollection property represents the filters registered with the system. The FilterCollection property represents the filters that are part of the filter graph.
As with other collections accessible to Visual Basic, you can access individual items in the collections by using the Visual Basic for each...next statement. The number of items in the collection is indicated by the Count property of the collection.
The filter collection contains IFilterInfo objects. Each IFilterInfo object has a Pins property that represents a collection of pins defined for that filter.
The pins collection contains IPinInfo objects. Each IPinInfo object includes detailed information about that pin, including its media type and its connection to another pin.
To examine a specific pin on a filter in the filter graph, use the following procedure.
There are three distinct ways to use Quartz.dll to create a filter graph; each way offers a different amount of control over the filter graph. These range from automatically generating the entire filter graph to specifying every filter and pin connection. The three approaches are as follows:
The following code fragment demonstrates how to generate the complete filter graph based on the multimedia source or stored filter graph. After creating an IMediaControl object that is initially "empty," the application calls the IMediaControl.RenderFile method to build up the complete graph.
' start by creating a new, empty filter graph; Dim g_objMC as IMediaControl ' from the General Declarations section ... Set g_objMC = New FilgraphManager ' create the new filter graph ' ... ' Use the common File Open dialog to let the user select the input file CommonDialog1.ShowOpen ' user selects a source or filter graph ' call IMediaControl.RenderFile to add all filters and connect all pins g_objMC.RenderFile CommonDialog1.filename ' generates the complete graph
The following code fragment demonstrates how to create the new (empty) filter graph object.
Dim g_objMC as IMediaControl ' from the General Declarations section ... Set g_objMC = New FilgraphManager ' create the new filter graph
When you choose to create an empty filter graph and add individual filters, you must know the filter type. In general, there are three categories of filters: source filters, transform filters, and renderer filters. The procedure for adding source filters uses a different method than the procedure for adding transform and renderer filters.
Add source filters to the filter graph by calling the IMediaControl.AddSourceFilter method and supplying the name of a file of the specified source type or stored filter graph.
Dim objFilter As Object ' temporary object for valid syntax; not used CommonDialog1.ShowOpen ' get the name of the source or filter graph file g_objMC.AddSourceFilter CommonDialog1.filename, objFilter
Add transform and renderer filters to the filter graph by calling the IRegFilterInfo.Filter method. The IRegFilterInfo object can be obtained from the IMediaControl.RegFilterCollection property, which represents the collection of filter objects registered with the system and available for use.
After creating the filter graph and obtaining the IMediaControl object, use the following procedure to add filters.
The following code fragment illustrates steps 1 and 2 in the previous procedure.
' code fragment that populates the registered filter list box ' global variable g_objRegFilters is set to IMediaControl.RegFilterCollection ' Set g_objRegFilters = g_objMC.RegFilterCollection Dim filter As IRegFilterInfo listRegFilters.Clear If Not g_objRegFilters Is Nothing Then For Each filter In g_objRegFilters ' for each filter in collection listRegFilters.AddItem filter.Name ' add name to the list box Next filter End If
The following code fragment illustrates step 3 in the previous procedure.
Dim filter As IRegFilterInfo ' find the selected filter and add it to the graph ' g_objRegFilters is the IMediaControl object RegFilterCollection property For Each filter In g_objRegFilters If filter.Name = listRegFilters.Text Then ' the selected filter? Dim f As IFilterInfo ' yes filter.filter f ' add to the filter graph, return IFilterInfo f If f.IsFileSource Then CommonDialog1.ShowOpen f.filename = CommonDialog1.filename End If Exit For End If Next filter
After adding individual filters to the filter graph, you can establish connections between the filters by explicitly connecting each pin, or by automatically generating all connections that are needed downstream from a specific pin.
In both cases, you must traverse the hierarchy of Microsoft® DirectShow® objects to obtain the IPinInfo object that represents a pin of the filter object. This involves finding the desired filter in the filter collection of the filter graph object, then finding the desired pin in the pin collection of the filter object.
This section contains the following topics.
All filters in the filter graph are available in a collection that you can access using the IMediaControl.FilterCollection property.
' refresh a list box that contains the current filters in the graph listFilters.Clear For Each objFI In g_objMC.FilterCollection listFilters.AddItem objFI.Name ' add to list box Next objFI
You can access the pins defined for a filter object through the IFilterInfo.Pins property. The Pins property is a collection of individual IPinInfo objects.
After you obtain an individual IPinInfo object from the collection, you can access its properties and call its methods, as shown in the following code fragment.
For Each objPin In g_objSelFilter.Pins If objPin.Name = listPins.Text Then ' selected pin? Set g_objSelPin = objPin ' yes, update information ' ... perform operations using that pin End If Next objPin
After you have obtained the pin object, you can explicitly connect to one other pin or automatically generate all subsequent pin connections needed to render the pin.
The IPinInfo object provides three methods to connect pins: Connect, ConnectDirect, and ConnectWithType. Connect adds other transform filters as needed, ConnectDirect does not add transform filters, and ConnectWithType performs the connection only if the specified pin matches the specified media type.
frmSelectPin.OtherDir = g_objSelPin.Direction Set frmSelectPin.Graph = g_objMC ' give that form a copy of the graph Set frmSelectPin.SelFilter = g_objSelFilter ' and the current filter frmSelectPin.RefreshFilters ' display available filters to connect frmSelectPin.Show 1 ' display the form If frmSelectPin.bOK Then ' user has selected one--used OK button Dim objPI As IPinInfo Set objPI = frmSelectPin.SelPin ' get the new pin from the form g_objSelPin.Connect objPI ' connect the two pins RefreshFilters ' display the latest pin information End If
Call the IPinInfo.Render method to automatically generate all portions of the filter graph that are needed downstream from that pin.
The term downstream refers to all connections needed to construct a complete path from that pin to a renderer filter. For example, consider the representation of the filter graph by the GraphEdit utility, which shows connections as moving from the source filter at the left to the renderer filter at the right. The Render method adds all required filters and connections to the right of the specified pin.
' call IPinInfo.Render ' complete the graph downstream from this pin ' g_objSelPin refers to the pin selected in the list box labeled 'Pins' g_objSelPin.Render
When you have obtained a pin object from the collection available from the IFilterInfo.Pins property of the filter object, you can list its connection and other information.
Dim strTemp As String On Error Resume Next Dim objPin As IPinInfo For Each objPin In g_objSelFilter.Pins If objPin.Name = listPins.Text Then ' selected in list box? Set g_objSelPin = objPin 'yes, get all information strTemp = "" ' clear existing displayed pin information Dim objPinOther As IPinInfo Set objPinOther = objPin.ConnectedTo If Err.Number = 0 Then ' yes, there is a connection strTemp = "Connected to pin: " + objPinOther.Name + " " Dim objPeer As IFilterInfo Set objPeer = objPinOther.FilterInfo strTemp = strTemp + " on filter: " + objPeer.Name + " " Dim objMTI As IMediaTypeInfo Set objMTI = objPin.ConnectionMediaType strTemp = strTemp + vbCrLf + "Media Type: " + objMTI.Type End If If objPin.Direction = 0 Then strTemp = strTemp + " " + vbCrLf + "Direction: Input" Else strTemp = strTemp + " " + vbCrLf + "Direction: Output" End If txtPinInfo.Text = strTemp End If Next objPin
In summary, this article discussed the use of the following DirectShow objects, properties, and methods.
Task | DirectShow properties or methods |
---|---|
Create a new, empty filter graph. | Set objMediaControl = New FilgraphManager. |
Generate the complete filter graph for a specific file. | Call the IMediaControl.RenderFile method. |
Add a source filter. | Call the IMediaControl.AddSourceFilter method. |
Add a renderer or transform filter. | Get the IRegFilterInfo objects using the IMediaControl.RegFilterCollection property; call the IRegFilterInfo.Filter method. |
List the pins of a filter object. | Get the IPinInfo objects using the IFilterInfo.Pins property. |
Explicitly connect two pins. | Call the IPinInfo.Connect method. |
Create all connections from the pin to the renderer filter. | Call the IPinInfo.Render method. |