《微软：DirectShow开发指南》第12章 Writing DirectShow Source Filters

Of the three classes of Microsoft DirectShow filters—source, transform, and renderer—the source filter is the one that generates the stream data manipulated by the filter graph. Every filter graph has at least one source filter, and by its nature the source filter occupies the ultimate upstream position in the filter graph, coming before any other filters. The source filter is responsible for generating a continuous stream of media samples, beginning when the Filter Graph Manager runs the filter graph and ceasing when the filter graph is paused or stopped.

在DS filter的三种类型中—源，转换，和渲染—源filter是由filter graph控制用来生成流数据。每个filter graph至少要有一个源filter 且位于第一级。源filter负责生成连续的媒体样本流，当Filter Graph Manager启动filter graph时开始，当filter graph暂停时或停止时结束。

 

Source Filter Types

In a broad sense, there are three types of source filters used in DirectShow filter graphs—capture source filters, file source filters, and “creator” source filters. We’re already quite familiar with capture source filters, such as the Microsoft DV Camcorder and VCR filter and the Logitech QuickCam Web filter, which we’ve used in numerous DirectShow applications. A capture source filter captures a live sample, converts it to a stream of media samples, and presents that stream on its output pins. Capture source filters are nearly always associated with devices, and in general, there’s rarely a need for DirectShow programmers to write their own capture source filters. Any device that has a correctly written Windows Driver Model (WDM) driver will automatically appear as a filter available to DirectShow applications. DirectShow puts a filter wrapper around WDM and Video for Windows (VFW) device drivers so that the capture device, for example, can be used in a filter graph as a capture source filter. (See Figure 12-1.) If you really want or need to write your own capture driver filter, you can find the gory details in the Microsoft DirectX SDK documentation and Windows DDK documentation.

从广义上来说，DS 的filter graph有三种类型的源filter—捕捉源filter, 文件源filter，和自生成源filter。通常比较熟悉的是捕捉源filter,如DV录像机和VCR filter和摄像头filter，它们已经在前面的章节中多次应用了。捕捉源filter将捕捉实时样本，将其转换成媒体样本流，并将其以流的形式传送到输出pin。捕捉源filter是和设备紧密相关的，而且通常，很少会需要DS程序员定他们自己的捕捉源filter。任何正确驱动了的WDM设备都会自动在DS应用程序中可用。DS还给WDM和VFW实现了一个filter封装以使捕捉设备能被filter graph的源捕捉filter使用。(如图12-1所示)。如果是真的要写一个捕捉驱动filter，可以到DirectX SDK文档去看看。

Figure 12-1. A capture source filter encapsulates a WDM interface to a hardware device

 

A file source filter acts as an interface between the world outside a DirectShow filter graph and the filter graph. The File Source filter, for example, makes the Microsoft Windows file system available to DirectShow; it allows the contents of a disk-based file to be read into the filter graph. (See Figure 12-2.) Another filter, the File Source URL filter, takes a URL as its parameter and allows Web-based files to be read into a filter graph. (This is a technique that could potentially be very powerful.) We’ve already used the Stream Buffer Engine’s source filter, a file source filter that reads stream data from files created by the Stream Buffer Engine’s sink filter. The ASF Reader filter takes an ASF file and generates media streams from its contents.

文件源filter扮演了filter graph和外部世界接口的角色。例如，文件源filter使得DS能访问文件系统;即可以将文件内容读进filter graph。(如图12-2所示)。其它的filter，如文件源URL filter， 可以将URL作为它的输入参数并将基于网络的文件读进filter graph。前面已经使用了流buffer引擎的源filter，它是由流buffer引擎的sink filter创建的从文件中读取流数据的文件源filter。ASF阅读filter能读取ASF文件并从中生成媒体流。

Figure 12-2. The File Source filter followed by a Wave Parser filter

 

With the notable exceptions of the SBE source filter and the ASF Reader, a file source filter normally sits upstream from a transform filter that acts as a file parser, translating the raw data read in by the file source filter into a series of media samples. The Wave Parser filter, for example, translates the WAV file format into a series of PCM media samples. Because the relationship between a file source filter and a parser filter is driven by the parser filter, the parser filter usually pulls the data from the file source filter. This is the reverse of the situation for capture (“live”) source filters, which produce a regular stream of media samples and then push them to a pin on a downstream filter. Unless you’re adding your own unique file media type to DirectShow, it’s unlikely you’ll need a custom parser transform filter. (You’re a bit on your own here. There aren’t any good examples of parser filters in the DirectX SDK samples.)

除了SBE源filter和ASF Reader这样的例外情况，文件源filter通常位于转换filter的上游，用来解析文件，读取文件的原始数据并转换成媒体样本序列。例如，Wave Parser filter, 就能将WAV文件格式转换成PCM媒体样本序列。因为文件源filter和解析filter都是源自解析filter的关系，解析filter通常会从文件源filter拉数据。这和捕捉“实时源filter—它能生成有规律的媒体样本流并将它们推到下一级filter的pin上—的情形是相反的。除非需要给DS开发自己定制的媒体文件格式，通常是不需要另行开发解析转换filter。

 

Finally there are source filters that create media samples in their entirety. This means that the sample data originates in the filter, based upon the internal settings and state of the filter. You can imagine a creator source filter acting as a “tone generator,” for example, producing a stream of PCM data reflecting a waveform of a particular frequency. (If it were designed correctly, the COM interfaces on such a filter would allow you to adjust the frequency on the fly with a method invocation.) Another creator source filter could produce the color bars that video professionals use to help them adjust their equipment, which would clearly be useful in a DirectShow application targeted at videographers.

对于内部自生成媒体样本的源filter来说，这些样本数据都是基于filter内部的设置和状态生成的。例如，可以将这样的自生成源filter看作是一个“音频发生器，它能生成反映特定频率的波形的PCM数据流。而其它的自生成源filter可以生成用于视频专家来调试设备的彩条，这个功能对于将DS应用程序用于电视制作人来说很有用。

Figure 12-3. The Generic Push Source filter creates its own media stream

 

The PushSource filter example explored in this chapter (and shown in Figure 12-3) is a creator source filter that produces a media stream with a numbered series of video frames and that stops automatically when a certain number of frames have been generated. (When a source filter runs dry, all filters downstream of it eventually stop, waiting for more stream data.) PushSource is not complicated and only scratches the surface of what’s possible with source filters. An excellent teaching example, PushSource exposes the internals of the source filter and, through that, much of how DirectShow handles the execution of the filter graph.

本章中(如图12-3所示)的PushSource filter是一个自生成源filter的例子，它能生成一个有固定视频序列的媒体流，视频帧数生成完成后自动停止。(当源filter运行数据干涸后，所有的下游filter都会最终停止，直到有数据流)。PushSource并不复杂而且它只涉及了源filter的一些基本工作。但是它是一个很好的例子，PushSource揭示了源filter的内部原理并介绍了它是如何在filter graph中工作的。

 

Source Filter Basics

As explained in the previous section, a source filter usually pushes its media samples to the input pin of a downstream filter. (The exception is file source filters.) Live sources, such as capture source filters, are always push sources because the data is generated somewhere outside the filter graph (such as in a camera or a microphone) and presented through a driver to the filter as a continuous stream of data. The PushSource filter covered in this chapter also pushes media samples to downstream filters, but these samples are generated in system memory rather than from a capture device.

如前所述，源filter会将它的媒体样本推到它下游filter的输入pin。(文件源filter是一个例外)，实时源，如捕捉源filter,都是推类型的源，因为这些数据通常是在filter graph外部生成的(例如摄像头和话筒)并能过驱动给filter作为连续的数据流。本章的PushSource filter同样也会将媒体样本推到下一级的filter，但是这些样本是在系统内存中生成的，而不是从捕捉设备生成。

 

A source filter generally doesn’t have any input pins, but it can have as many output pins as desired. As an example, a source filter could have both capture and preview pins, or video and audio pins, or color and black-and-white pins. Because the output pins on a source filter are the ultimate source of media samples in the filter graph, the source filter fundamentally controls the execution of the filter graph. Filters downstream of a source filter will not begin execution until they receive samples from the source filter. If the source filter stops pushing samples downstream, the downstream filters will empty their buffers of media samples and then wait for more media samples to arrive.

源filter通常不需要任何输入pin，但是可能依据需求有多个输出pin。作为一个示例程序，源filter可以有捕捉和预览pin，或视频和音频pin，或彩色和黑白pin。因为源filter上的输出pin是最终的filter graph的媒体样本源，源filter从根本上控制了filter graph的执行。源filter的下游filter在没有收到源filter的样本时是不会执行的。如果源filter停止向下游推送样本，那么下游filter将会清空它们的媒体样本缓存区并等待媒体样本的到来。

 

The DirectShow filter graph has at least two execution threads: one or more streaming threads and the application thread. The application thread is created by the Filter Graph Manager and handles messages associated with filter graph execution, such as run, pause, and stop. You’ll have one streaming thread per source filter in the filter graph, so a filter graph with separate source filters to capture audio and video would have at least two streaming threads. A streaming thread is typically shared by all the filters downstream of the source filter that creates it (although downstream filters can create their own threads for special processing needs, as parsers do regularly), and it’s on these threads that transforms and rendering occur.

DS的filter graph至少有两个执行线程：一个或多个流线程和一个应用程序线程。应用程序线程由Filter Graph Manager创建并处理filter graph的消息，如运行，暂停，和停止。在filter graph的每个源filter都一个流线程，因此，用来捕捉音频和视频的分立源filter的filter graph至少有两个流线程。流线程通常会被创建了它的源filter的所有下游filter所共享(尽管下游filter也可以根据需要创建它们自己的线程，像解析器通常所做的)，转换和渲染都是在这个线程上执行。

 

Once the streaming thread has been created, it enters a loop with the following steps. A free (that is, empty) sample is acquired from the allocator. This sample is then filled with data, timestamped, and delivered downstream. If no samples are available, the thread blocks until a sample becomes available. This loop is iterated as quickly as possible while the filter graph is executing, but the renderer filter can throttle execution of the filter graph. If a renderer’s sample buffers fill up, filters upstream are forced to wait while their buffers fill up, a delay that could eventually propagate all the way back to the source filter. A renderer might block the streaming thread for one of two reasons: the filter graph could be paused, in which case the renderer is not rendering media samples (and the graph backs up with samples); or the renderer could be purposely slowing the flow of samples through the filter graph to ensure that each sample is presented at the appropriate time. When the renderer doesn’t care about presentation time—such as in the case of a filter that renders to a file—the streaming thread runs as quickly as possible.

当流线程被创建后，它就进入下面的循环。向分配器请求一个空样本，这个空样本会接着被填充数据，时间戳，并传送给下一级。如果没有样本可用，那么线程就阻塞直到有样本可用。这个循环在filter graph执行时会尽可能地快，但是渲染filter能减速filter graph的执行。如果渲染filter的样本缓存区已满，那么上游的filter将会被强制等待，通过这种方式，延迟会最终传播到源filter。渲染器将会阻塞线程流的另两个原因是：filter graph可以暂停，在这种情况下渲染器停止媒体样本的渲染(但filter graph备份了媒体样本)；或者渲染器通过filter graph有意地减慢样本流以确保每个样本都在合适的时间表示。当渲染器不关心表示时间时—如写文件的filter—那么流线程就可以运行得尽可能地快。

 

Seeking functionality should be implemented by the source filters where appropriate. Downstream filters and the Filter Graph Manager can use the IMediaSeeking interface to rewind or fast-forward through a stream. Seeking a live stream doesn’t have to be implemented (it could be useful, such as in the case of a TV broadcast), but source filters should be able to seek as appropriate. When a seek command is issued, the Filter Graph Manager distributes it to all the filters in the filter graph. The command propagates upstream across the filter graph, from input pin to output pin, until a filter that can accept and process the seek command is found. Typically, the filter that creates the streaming thread implements the seek command because that filter is the one providing the graph with media samples and therefore can be sent requests for earlier or later samples. This is generally a source filter, although it can also be a parser transform filter.

查找功能适合在源filter中实现。下游filter和Filter Graph Manager可以使用IMediaSeeking接口来回退和快进流。在实时流中查找没有实现，但是源filter应该以适当的方式查找。当查找命令发出后，Filter Graph Manager会将这个命令发给filter graph中的所有filter。它是在filter graph中向上传播的，从输入pin到输出pin,直到发现有一个filter能接受并处理这个查找命令。通常，创建流线程的filter会实现查找命令，因为是它提供了媒体样本并能请求向前或向后的样本。这样的filter通常是源filter,也可以是解析用的转换filter。

 

When a source filter responds to a seek command, the media samples flowing through the filter graph change abruptly and discontinuously. The filter graph needs to flush all the data residing in the buffers of all downstream filters because all the data in the filter graph has become “stale”; that is, no longer synchronized with the new position in the media stream. The source filter flushes the data by issuing an IPin::BeginFlush call on the pin immediately downstream of the filter. This command forces the downstream filter to flush its buffers, and that downstream filter propagates the IPin::BeginFlush command further downstream until it encounters a renderer filter. The whole process of seeking and flushing looks like that shown in Figure 12-4. Both seek and flush commands are executed on the application thread, independent of the streaming thread.

当源filter响应查找命令时，流经filter graph的媒体样本会中断和改变。Filter graph需要所有下游filter的缓存区中的数据，因为此时filter graph中的所有数据都变得“过时了；而且对于新位置来说，媒体流也失去了同步。源filter通过调用IPin::BeginFlush清空数据。这个命令会强制下游filter清空它的缓存区，并将IPin::BeginFlush命令传播到下游filter直到渲染filter。整个查找和清空的过程可见图12-4。查找和清空命令都是在应用程序线程中执行，独立于流线程。

Figure 12-4. Seek and flush commands move in opposite directions across the filter graph

 

PushSource Source Filter

The PushSource source filter example generates a stream of black video frames (in RGB32 format) that have yellow frame numbers printed on them. The PushSource filter generates frames at a rate of 30 per second at standard video speed, and it will keep going for 10 seconds (the value set by the DEFAULT_DURATION constant) for a total of 300 frames. In operation, the PushSource filter—which appears in the list of DirectShow filters under the name “Generic Push Source”—looks like Figure 12-5.

PushSource 源filter的例子会生成一个RGB32格式黑色背景黄色帧数字的流，其帧率为30帧/秒，保持10秒共计300帧。在操作上，PushSource filter—DS filter的名称为“Generic Push Sourc—如图12-5所示。

Figure 12-5. The PushSource filter creating a video stream with numbered frames

 

The DirectShow C base classes include three classes that are instrumental in implementing PushSource: CSource, which implements a basic source filter; CSourceStream, which implements the presentation of a stream on the source filter’s output pin; and CSourceSeeking, which implements the seek command on the output pin of the source filter. If your source filter has more than one output pin (some do, most don’t), you can’t use CSourceSeeking as a basis for an implementation of the seek command. In that case, you’d need to coordinate between the two pins, which requires careful thread synchronization that CSourceSeeking doesn’t handle. (You can use CSourceStream for multiple output pins.) In a simple source filter, such as PushSource, only a minimal implementation is required and nearly all of that is in the implementation of methods in CSourceStream and CSourceSeeking.

DirectShow C 基类包含了三个类，它们在实现PushSourc::CSource上各有任用并共同实现了一个基本的源filter:

  CSourceStream: 实现了源filter的输出pin上的流的表示；

  CSourceSeeking: 查找命令的基本实现，在这种情况下，需要两个pin的协作。

在PushSource这个比较简单的例子中，只需要CSourceStream和CSourceSeeking的简单实现。

 

Implementing the Source Filter Class

The implementation of the source filter class CPushSource for the PushSource example is entirely straightforward. Only two methods need to be overridden: the class constructor, which creates the output pin, and CPushSource::CreateInstance, which calls the class constructor to create an instance of the filter. Here’s the complete implementation of CPushSource:

PushSource的源filter类CPushSource的实现很简单。只有两个方法需要覆盖：类构造函数，它创建了输出pin。CPushSource::CreateInstance, 它调用了类构造函数来创建filter的实例。下面的代码是CPushSource的完整实现：

点击(此处)折叠或打开

1. // CPushSource class: Our source filter.
   
2. class CPushSource : public CSource
   
3. {
   
4.   private:
   
5.   // Constructor is private
   
6.   // You have to use CreateInstance to create it.
   
7.   CPushSource(IUnknown *pUnk, HRESULT *phr);
   
8.   public:
   
9.   static CUnknown * WINAPI CreateInstance(IUnknown *pUnk, HRESULT *phr);
   
10. };
    
11. 
    
12. CPushSource::CPushSource(IUnknown *pUnk, HRESULT *phr)
    
13. : CSource(NAME("PushSource"), pUnk, CLSID_PushSource)
    
14. {
    
15.   // Create the output pin.
    
16.   // The pin magically adds itself to the pin array.
    
17.   CPushPin *pPin = new CPushPin(phr, this);
    
18.   if (pPin == NULL)
    
19.   {
    
20.     *phr = E_OUTOFMEMORY;
    
21.   }
    
22. }
    
23. CUnknown * WINAPI CPushSource::CreateInstance(IUnknown *pUnk, HRESULT *phr)
    
24. {
    
25.   CPushSource *pNewFilter = new CPushSource(pUnk, phr );
    
26.   if (pNewFilter == NULL)
    
27.   {
    
28.     *phr = E_OUTOFMEMORY;
    
29.   }
    
30.   return pNewFilter;
    
31. }

This is all the code required to create the source filter object.

这就是创建源filter对象的所有代码。

 

Implementing the Source Filter Output Pin Class

All the real work in the PushSource filter takes place inside the filter’s output pin. The output pin class, CPushPin, is declared as a descendant of both the CSourceStream and CSourceSeeking classes, as shown in the following code:

PushSource filter的所有实际工作都是发生成filter的输出pin内部，输出pin类，CPushPin,被声明为CSourceStream和CSourceSeeking的继承类，如下源码所示：

点击(此处)折叠或打开

1. class CPushPin : public CSourceStream, public CSourceSeeking
   
2. {
   
3.   private:
   
4.   REFERENCE_TIME m_rtStreamTime; // Stream time (relative to  when the graph started)
5.   REFERENCE_TIME m_rtSourceTime; // Source time (relative to  ourselves)
6. 
   
7.   // A note about seeking and time stamps:
   
8.   // Suppose you have a file source that is N seconds long.
   
9.   // If you play the file from
   
10.   // the beginning at normal playback rate (1x),
    
11.   // the presentation time for each frame
    
12.   // will match the source file:
    
13.   // Frame: 0 1 2 ... N
    
14.   // Time: 0 1 2 ... N
    
15.   // Now suppose you seek in the file to an arbitrary spot,
    
16.   // frame i. After the seek
    
17.   // command, the graph's clock resets to zero.
    
18.   // Therefore, the first frame delivered
    
19.   // after the seek has a presentation time of zero:
    
20.   // Frame: i i+1 i+2 ...
    
21.   // Time: 0 1 2 ...
    
22.   // Therefore we have to track
    
23.   // stream time and source time independently.
    
24.   // (If you do not support seeking,
    
25.   // then source time always equals presentation time.)
    
26.   REFERENCE_TIME m_rtFrameLength;    // Frame length
    
27.   int m_iFrameNumber;                // Current frame number that we are rendering
    
28.   BOOL m_bDiscontinuity;             // If true, set the discontinuity flag
    
29.   CCritSec m_cSharedState;           // Protects our internal state
    
30.   ULONG_PTR m_gdiplusToken;          // GDI+ initialization token
    
31. 
    
32.   // Private function to draw our bitmaps.
    
33.   HRESULT WriteToBuffer(LPWSTR wszText, BYTE *pData,
    
34.                         VIDEOINFOHEADER *pVih);
    
35. 
    
36.   // Update our internal state after a seek command.
    
37.   void UpdateFromSeek();
    
38. 
    
39.   // The following methods support seeking
    
40.   // using other time formats besides
    
41.   // reference time. If you want to support only
    
42.   // seek-by-reference-time, you
    
43.   // do not have to override these methods.
    
44.   STDMETHODIMP SetTimeFormat(const GUID *pFormat);
    
45.   STDMETHODIMP GetTimeFormat(GUID *pFormat);
    
46.   STDMETHODIMP IsUsingTimeFormat(const GUID *pFormat);
    
47.   STDMETHODIMP IsFormatSupported(const GUID *pFormat);
    
48.   STDMETHODIMP QueryPreferredFormat(GUID *pFormat);
    
49.   STDMETHODIMP ConvertTimeFormat(LONGLONG *pTarget,
    
50.                                  const GUID *pTargetFormat,
    
51.                                  LONGLONG Source,
    
52.                                  const GUID *pSourceFormat );
    
53.   STDMETHODIMP SetPositions(LONGLONG *pCurrent, DWORD CurrentFlags,
    
54.   LONGLONG *pStop, DWORD StopFlags);
    
55.   STDMETHODIMP GetDuration(LONGLONG *pDuration);
    
56.   STDMETHODIMP GetStopPosition(LONGLONG *pStop);
    
57. 
    
58.   // Conversions between reference times and frame numbers.
    
59.   LONGLONG FrameToTime(LONGLONG frame) {
    
60.     LONGLONG f = frame * m_rtFrameLength;
    
61.     return f;
    
62.   }
    
63. 
    
64.   LONGLONG TimeToFrame(LONGLONG rt) { return rt / m_rtFrameLength; }
    
65.   GUID m_TimeFormat; // Which time format is currently active
66. 
    
67. protected:
68.   // Override CSourceStream methods.
    
69.   HRESULT GetMediaType(CMediaType *pMediaType);
    
70.   HRESULT CheckMediaType(const CMediaType *pMediaType);
    
71.   HRESULT DecideBufferSize(IMemAllocator *pAlloc,
    
72.   ALLOCATOR_PROPERTIES *pRequest);
    
73.   HRESULT FillBuffer(IMediaSample *pSample);
    
74. 
    
75.   // The following methods support seeking.
    
76.   HRESULT OnThreadStartPlay();
    
77.   HRESULT ChangeStart();
    
78.   HRESULT ChangeStop();
    
79.   HRESULT ChangeRate();
    
80.   STDMETHODIMP SetRate(double dRate);
    
81. 
    
82. public:
    
83.   CPushPin(HRESULT *phr, CSource *pFilter);
    
84.   ~CPushPin();
    
85. 
    
86.   // Override this to expose ImediaSeeking.
    
87.   STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv);
    
88. 
    
89.   // We don't support any quality control.
    
90.   STDMETHODIMP Notify(IBaseFilter *pSelf, Quality q)
    
91.   {
    
92.     return E_FAIL;
    
93.   }
    
94. };

Let’s begin with an examination of the three public methods defined in CPushPin and implemented in

the following code: the class constructor, the destructor, and CPushPin::NonDelegatingQueryInterface.

下面看CPushPin的三个公共方法，类构造函数，析构函数和CPushPin::NonDelegatingQueryInterface的定义：

点击(此处)折叠或打开

1. CPushPin::CPushPin(HRESULT *phr, CSource *pFilter)
   
2.   : CSourceStream(NAME("CPushPin"), phr, pFilter, L"Out"),
   
3.     CSourceSeeking(NAME("PushPin2Seek"), (IPin*)this, phr, &m_cSharedState),
   
4.                    m_rtStreamTime(0),
   
5.                    m_rtSourceTime(0),
   
6.                    m_iFrameNumber(0),
   
7.                    m_rtFrameLength(Fps2FrameLength(DEFAULT_FRAME_RATE))
   
8. {
   
9.   // Initialize GDI+.
   
10.   GdiplusStartupInput gdiplusStartupInput;
    
11.   Status s = GdiplusStartup(&m_gdiplusToken, &gdiplusStartupInput, NULL);
    
12.   if (s != Ok)
    
13.   {
    
14.     *phr = E_FAIL;
    
15.   }
    
16. 
    
17.   // SEEKING: Set the source duration and the initial stop time.
    
18.   m_rtDuration = m_rtStop = DEFAULT_DURATION;
    
19.   CPushPin::~CPushPin()
    
20.   {
    
21.     // Shut down GDI+.
    
22.     GdiplusShutdown(m_gdiplusToken);
    
23.   }
    
24. 
    
25.   STDMETHODIMP CPushPin::NonDelegatingQueryInterface(REFIID riid, void **ppv)
    
26.   {
    
27.     if( riid == IID_IMediaSeeking )
    
28.     {
    
29.       return CSourceSeeking::NonDelegatingQueryInterface( riid, ppv );
    
30.     }
    
31.     return CSourceStream::NonDelegatingQueryInterface(riid, ppv);
    
32.   }

The class constructor invokes the constructors for the two ancestor classes of CPushPin, CSourceStream and CSourceSeeking, and then the GDI+ (Microsoft’s 2D graphics library) is initialized. GDI+ will create the numbered video frames streamed over the pin. The class destructor shuts down GDI+, and CPushPin::NonDelegatingQueryInterface determines whether a QueryInterface call issued to the PushSource filter object is handled by CSourceStream or CSourceSeeking. Because only seek commands are handled by CSourceSeeking, only those commands are passed to that implementation.

类构造函数调用了CPushPin的两个父类CSourceStream和CSourceSeeking的构造函数，然后初始化了GDI+(微软的2D图形库)。GDI+将会创建pin上的有编号的视频帧流。类析构函数用来关闭GDI+。CPushPin::NonDelegatingQueryInterface确认是否发送给PushSource filter对象的QueryInterface调用可以被 CSourceStream 和CSourceSeeking处理。因为只有查找命令能被CSourceSeeking处理，只有这些命令被传输给这些实现。

 

Negotiating Connections on a Source Filter

CPushPin has two methods to handle the media type negotiation, CPushPin::GetMediaType and CPushPin::CheckMediaType. These methods, together with the method CPushPin::DecideBufferSize, handle pin-to-pin connection negotiation, as implemented in the following code:

CPushPin有两个处理媒体类型协商的方法，CPushPin::GetMediaType和CPushPin::CheckMediaType。这两个方法再加上CPushPin::DecideBufferSize方法一起处理pin到pin的连接协商。代码实现如下：

点击(此处)折叠或打开

1. HRESULT CPushPin::GetMediaType(CMediaType *pMediaType)
   
2. {
   
3.   CheckPointer(pMediaType, E_POINTER);
   
4.   CAutoLock cAutoLock(m_pFilter->pStateLock());
   
5. 
   
6.   // Call our helper function that fills in the media type.
   
7.   return CreateRGBVideoType(pMediaType, 32, DEFAULT_WIDTH,
   
8.   DEFAULT_HEIGHT, DEFAULT_FRAME_RATE);
   
9. }
   
10. 
    
11. HRESULT CPushPin::CheckMediaType(const CMediaType *pMediaType)
    
12. {
    
13.   CAutoLock lock(m_pFilter->pStateLock());
    
14. 
    
15.   // Is it a video type?
    
16.   if (pMediaType->majortype != MEDIATYPE_Video)
    
17.   {
    
18.     return E_FAIL;
    
19.   }
    
20. 
    
21.   // Is it 32-bit RGB?
    
22.   if ((pMediaType->subtype != MEDIASUBTYPE_RGB32))
    
23.   {
    
24.     return E_FAIL;
    
25.   }
    
26. 
    
27.   // Is it a VIDEOINFOHEADER type?
    
28.   if ((pMediaType->formattype == FORMAT_VideoInfo) &&
    
29.       (pMediaType->cbFormat >= sizeof(VIDEOINFOHEADER)) &&
    
30.       (pMediaType->pbFormat != NULL))
    
31.   {
    
32.     VIDEOINFOHEADER *pVih = (VIDEOINFOHEADER*)pMediaType->pbFormat;
    
33. 
    
34.     // We don't do source rects.
    
35.     if (!IsRectEmpty(&(pVih->rcSource)))
    
36.     {
    
37.       return E_FAIL;
    
38.     }
    
39. 
    
40.     // Valid frame rate?
    
41.     if (pVih->AvgTimePerFrame != m_rtFrameLength)
    
42.     {
    
43.       return E_FAIL;
    
44.     }
    
45. 
    
46.     // Everything checked out.
    
47.     return S_OK;
    
48.   }
    
49.   return E_FAIL;
    
50. }
    
51. 
    
52. HRESULT CPushPin::DecideBufferSize(IMemAllocator *pAlloc,
    
53.                                    ALLOCATOR_PROPERTIES *pRequest)
    
54. {
    
55.   CAutoLock cAutoLock(m_pFilter->pStateLock());
    
56.   HRESULT hr;
    
57.   VIDEOINFO *pvi = (VIDEOINFO*) m_mt.Format();
    
58.   ASSERT(pvi != NULL);
    
59.   if (pRequest->cBuffers == 0)
    
60.   {
    
61.     pRequest->cBuffers = 1; // We need at least one buffer
    
62.   }
    
63. 
    
64.   // Buffer size must be at least big enough to hold our image.
    
65.   if ((long)pvi->bmiHeader.biSizeImage > pRequest->cbBuffer)
    
66.   {
    
67.     pRequest->cbBuffer = pvi->bmiHeader.biSizeImage;
    
68.   }
    
69. 
    
70.   // Try to set these properties.
    
71.   ALLOCATOR_PROPERTIES Actual;
    
72.   hr = pAlloc->SetProperties(pRequest, &Actual);
    
73.   if (FAILED(hr))
    
74.   {
    
75.     return hr;
    
76.   }
    
77. 
    
78.   // Check what we actually got.
    
79.   if (Actual.cbBuffer < pRequest->cbBuffer)
    
80.   {
    
81.     return E_FAIL;
    
82.   }
    
83.   return S_OK;
    
84. }

All three methods begin with the inline creation of a CAutoLock object, a class DirectShow uses to lock a critical section of code. The lock is released when CAutoLock’s destructor is called—in this case, when the object goes out of scope when the method exits. This is a clever and simple way to implement critical sections of code. CPushPin::GetMediaType always returns a media type for RGB32 video because that’s the only type it supports. The media type is built in a call to CreateRGBVideoType, a helper function that can be easily rewritten to handle the creation of a broader array of media types. CPushPin::CheckMediaType ensures that any presented media type exactly matches the RGB32 type supported by the pin; any deviation from the one media type supported by the pin results in failure. Finally, CPushPin::DecideBufferSize examines the size of each sample (in this case, a video frame) and requests at least one buffer of that size. The method will accept more storage if offered but will settle for no less than that minimum amount. These three methods must be implemented by every source filter.

这三个方法都是从创建CAutoLock对象开始，这个类是DS用来锁定重要的代码段。当CAutoLock的解析函数被调用进这个锁就被释放了—在现在的这个例子中，当这个方法结束时这个锁对象也就超出了作用域。这是一个聪明而简单的方式实现重要的代码段。

CPushPin::GetMediaType方法总是为RGB32视频返回一个媒体类型，因为这是它唯一支持的类型。媒体类型是通过调用CreateRGBVideoType创建的，CreateRGBVideoType是一个辅助函数，能比较容易地重写来处理更广泛的媒体类型数组的生成。

CPushPin::CheckMediaType用来确保任何出现在pin上的媒体类型和pin支持的RGB32类型相匹配；任何偏离了pin支持的媒体类型将会导致失败

CPushPin::DecideBufferSize检查每个样本(在本例中是视频帧)的大小并至少申请这么大的缓存区。这个方法可以申请更多的存储空间,如果能够提供但会勉强接受不低于最低数额。这三个方法是每个源filter都必须实现的。

 

Implementing Media Sample Creation Methods

One media sample creation method must be implemented with CPushPin. This is the method by which video frames are created and passed along as media samples. When the streaming thread is created, it goes into a loop, and CPushPin::FillBuffer is called every time through the loop as long as the filter is active (either paused or running). In CPushPin, this method is combined with another, internal, method, CPushPin::WriteToBuffer, which actually creates the image, as shown in the following code:

生成媒体样本的方法也要在CPushPin中实现。它是视频帧被生成并作为样传输的方法。当流线程被创建后，它就自动进入一个循环，filter被激活后，CPushPin::FillBuffer在每次循环中都会被调用。在CPushPin中，这个方法和另一个内部的方法CPushPin::WriteToBuffer(它实际上用来创建图像)结合到一起使用。代码如下：

点击(此处)折叠或打开

1. HRESULT CPushPin::FillBuffer(IMediaSample *pSample)
   
2. {
   
3.   HRESULT hr;
   
4.   BYTE *pData;
   
5.   long cbData;
   
6.   WCHAR msg[256];
   
7. 
   
8.   // Get a pointer to the buffer.
   
9.   pSample->GetPointer(&pData);
   
10.   cbData = pSample->GetSize();
    
11. 
    
12.   // Check if the downstream filter is changing the format.
    
13.   CMediaType *pmt;
    
14.   hr = pSample->GetMediaType((AM_MEDIA_TYPE**)&pmt);
    
15.   if (hr == S_OK)
    
16.   {
    
17.     SetMediaType(pmt);
    
18.     DeleteMediaType(pmt);
    
19.   }
    
20. 
    
21.   // Get our format information
    
22.   ASSERT(m_mt.formattype == FORMAT_VideoInfo);
    
23.   ASSERT(m_mt.cbFormat >= sizeof(VIDEOINFOHEADER));
    
24.   VIDEOINFOHEADER *pVih = (VIDEOINFOHEADER*)m_mt.pbFormat;
    
25.   {
    
26.     // Scope for the state lock,
    
27.     // which protects the frame number and ref times.
    
28.     CAutoLock cAutoLockShared(&m_cSharedState);
    
29. 
    
30.     // Have we reached the stop time yet?
    
31.     if (m_rtSourceTime >= m_rtStop)
    
32.     {
    
33.       // This will cause the base class
    
34.       // to send an EndOfStream downstream.
    
35.       return S_FALSE;
    
36.     }
    
37. 
    
38.     // Time stamp the sample.
    
39.     REFERENCE_TIME rtStart, rtStop;
    
40.     rtStart = (REFERENCE_TIME)(m_rtStreamTime / m_dRateSeeking);
    
41.     rtStop = rtStart + (REFERENCE_TIME)(pVih->AvgTimePerFrame / m_dRateSeeking);
42.     pSample->SetTime(&rtStart, &rtStop);
    
43. 
    
44.     // Write the frame number into our text buffer.
    
45.     swprintf(msg, L"%d", m_iFrameNumber);
    
46. 
    
47.     // Increment the frame number
    
48.     // and ref times for the next time through the loop.
    
49.     m_iFrameNumber++;
    
50.     m_rtSourceTime += pVih->AvgTimePerFrame;
    
51.     m_rtStreamTime += pVih->AvgTimePerFrame;
    
52.   }
    
53. 
    
54.   // Private method to draw the image.
    
55.   hr = WriteToBuffer(msg, pData, pVih);
    
56.   if (FAILED(hr))
    
57.   {
    
58.     return hr;
    
59.   }
    
60. 
    
61.   // Every frame is a key frame.
    
62.   pSample->SetSyncPoint(TRUE);
    
63.   return S_OK;
    
64. }
    
65. 
    
66. HRESULT CPushPin::WriteToBuffer(LPWSTR wszText, BYTE *pData,
    
67. VIDEOINFOHEADER *pVih)
    
68. {
    
69.   ASSERT(pVih->bmiHeader.biBitCount == 32);
    
70.   DWORD dwWidth, dwHeight;
    
71.   long lStride;
    
72.   BYTE *pbTop;
    
73. 
    
74.   // Get the width, height, top row of pixels, and stride.
    
75.   GetVideoInfoParameters(pVih, pData, &dwWidth, &dwHeight,
    
76.                          &lStride, &pbTop, false);
    
77. 
    
78.   // Create a GDI+ bitmap object to manage our image buffer.
    
79.   Bitmap bitmap((int)dwWidth, (int)dwHeight, abs(lStride),
    
80.                  PixelFormat32bppRGB, pData);
    
81. 
    
82.   // Create a GDI+ graphics object to manage the drawing.
    
83.   Graphics g(&bitmap);
    
84. 
    
85.   // Turn on anti-aliasing.
    
86.   g.SetSmoothingMode(SmoothingModeAntiAlias);
    
87.   g.SetTextRenderingHint(TextRenderingHintAntiAlias);
    
88. 
    
89.   // Erase the background.
    
90.   g.Clear(Color(0x0, 0, 0, 0));
    
91. 
    
92.   // GDI+ is top-down by default,
    
93.   // so if our image format is bottom-up, we need
    
94.   // to set a transform on the Graphics object to flip the image.
    
95.   if (pVih->bmiHeader.biHeight > 0)
    
96.   {
    
97.     // Flip the image around the X axis.
    
98.     g.ScaleTransform(1.0, -1.0);
    
99. 
    
100.     // Move it back into place.
     
101.     g.TranslateTransform(0, (float)dwHeight, MatrixOrderAppend);
     
102.   }
     
103. 
     
104.   SolidBrush brush(Color(0xFF, 0xFF, 0xFF, 0)); // Yellow brush
     
105.   Font font(FontFamily::GenericSerif(), 48);    // Big serif type
     
106.   RectF rcBounds(30, 30, (float)dwWidth,
     
107.                  (float)dwHeight);              // Bounding rectangle
     
108. 
     
109.   // Draw the text
     
110.   g.DrawString(
     
111.   wszText, -1,
     
112.   &font,
     
113.   rcBounds,
     
114.   StringFormat::GenericDefault(),
     
115.   &brush);
     
116.   return S_OK;
     
117. }

Upon entering CPushPin::FillBuffer, the media sample is examined for a valid media type. Then a thread lock is executed, and the method determines whether the source filter’s stop time has been reached. If it has, the routine returns S_FALSE, indicating that a media sample will not be generated by the method. This will cause the downstream buffers to empty, leaving filters waiting for media samples from the source filter.

具体来看CPushPin::FillBuffer，为了有效的媒体类型先要检查媒体样本。然后执行线程锁，并且这个方法会确认这个源filter是否到了停止的时间。如果是，则返回失败，表示这个方法没有生成媒体本校。这将会导致下游的缓存区清空，并等待源filter的媒体样本的到来。

 

If the filter stop time has not been reached, the sample’s timestamp is set with a call to IMediaSample::SetTime. This timestamp is composed of two pieces (both in REFERENCE_TIME format of 100-nanosecond intervals), indicating the sample’s start time and stop time. The calculation here creates a series of timestamps separated by the time per frame (in this case, one thirtieth of a second). At this point, the frame number is written to a string stored in the object and then incremented.

如果filter还没有到停止时间，那么就调用IMediaSample::SetTime来设置样本的时间戳。这个时间戳由两部分组成(100纳秒的REFERENCE_TIME格式)，指示样本的开始和结束时间。这里的这个计算创建了每个帧独立的时间戳。此时，帧号被存储在对象的字符串变量中并累加。

 

That frame number is put to work in CPushPin::WriteToBuffer, which creates the RGB32-based video frame using GDI+. The method makes a call to the helper function GetVideoInfoParameters, retrieving the video parameters it uses to create a bitmap of appropriate width and height. With a few GDI+ calls, CPushPin::WriteToBuffer clears the background (to black) and then inverts the drawing image if the video format is bottom-up rather than top-down (the default for GDI+). A brush and then a font are selected, and the frame number is drawn to the bitmap inside a bounding rectangle.

帧号是给CPushPin::WriteToBuffer工作的，它使用GDI+创建基于RGB32的视频帧。这个方法调用了辅助函数GetVideoInfoParameters—它会返回用于创建合适宽度位图的视频参数。通过少量的GDI+调用，CPushPin::WriteToBuffer清除了背景成黑色然后转换图像。然后选择刷子和字体，并将帧号绘制位图到背景框。

 

Seek Functionality on a Source Filter

CPushPin inherits from both CSourceStream and CSourceSeeking. CSourceSeeking allows the source filter’s output pin to process and respond to seek commands. In the case of the PushSource filter, a seek command causes the frame count to rewind or fast-forward to a new value. Because this filter is frame-seekable (meaning we can position it to any arbitrary frame within the legal range), it needs to implement a number of other methods. The following code shows the basic methods that implement seek functionality:

CPushPin 继承自CSourceStream和CSourceSeeking，CSourceSeeking允许源filter的输出pin能处理和响应查找命令。在CPushPin这个例子中，查找命令会造成帧号向前或向后到一个新值。因为filter是帧事查找，它需要实现一些其它的函数。下面的代码显示了查找功能的基本方法要实现的代码。

点击(此处)折叠或打开

1. void CPushPin::UpdateFromSeek()
   
2. {
   
3.   if (ThreadExists())       // Filter is active?
   
4.   {
   
5.     DeliverBeginFlush();
   
6. 
   
7.     // Shut down the thread and stop pushing data.
   
8.     Stop();
   
9.     DeliverEndFlush();
   
10. 
    
11.     // Restart the thread and start pushing data again.
    
12.     Pause();
    
13.     // We'll set the discontinuity flag on the next sample.
    
14.   }
    
15. }
    
16. 
    
17. HRESULT CPushPin::OnThreadStartPlay()
    
18. {
    
19.   m_bDiscontinuity = TRUE;        // Set the discontinuity flag on the next sample
    
20. 
    
21.   // Send a NewSegment call downstream.
    
22.   return DeliverNewSegment(m_rtStart, m_rtStop, m_dRateSeeking);
    
23. }
    
24. HRESULT CPushPin::ChangeStart( )
    
25. {
    
26.   // Reset stream time to zero and the source time to m_rtStart.
    
27.   {
    
28.     CAutoLock lock(CSourceSeeking::m_pLock);
    
29.     m_rtStreamTime = 0;
    
30.     m_rtSourceTime = m_rtStart;
    
31.     m_iFrameNumber = (int)(m_rtStart / m_rtFrameLength);
    
32.   }
    
33.   UpdateFromSeek();
    
34.   return S_OK;
    
35. }
    
36. HRESULT CPushPin::ChangeStop( )
    
37. {
    
38.   {
    
39.     CAutoLock lock(CSourceSeeking::m_pLock);
    
40.     if (m_rtSourceTime < m_rtStop)
    
41.     {
    
42.       return S_OK;
    
43.     }
    
44.   }
    
45. 
    
46.   // We're already past the new stop time. Flush the graph.
    
47.   UpdateFromSeek();
    
48.   return S_OK;
    
49. }
    
50. 
    
51. //HRESULT CPushPin::SetRate(double {
    
52. if (dRate <= 0.0)
    
53. {
    
54.   return E_INVALIDARG;
    
55. }
    
56. {
    
57.   CAutoLock lock(CSourceSeeking::m_pLock);
    
58.   m_dRateSeeking = dRate;
    
59. }
    
60. UpdateFromSeek();
    
61. return S_OK;
    
62. }
    
63. 
    
64. // Because we override SetRate,
    
65. // the ChangeRate method won't ever be called. (It is only
    
66. // ever called by SetRate.)
    
67. // But it's pure virtual, so it needs a dummy implementation.
    
68. HRESULT CPushPin::ChangeRate() { return S_OK; }

CPushPin::UpdateFromSeek forces the flush of the filter graph that needs to take place every time a seek is performed on the source filter. The buffer flushing process has four steps. Flushing begins (on the downstream pin) when DeliverBeginFlush is invoked. Next the streaming thread is stopped, suspending buffer processing throughout the filter graph. Then DeliverEndFlush is invoked; this sets up the downstream filters to receive new media samples. The streaming thread is then restarted. When restarted, CPushPin::OnThreadStartPlay is called, and any processing associated with starting the filter must be performed here. The new start, stop, and rate values for the stream are delivered downstream. If the filter does anything complicated to the threads, it’s not hard to create a deadlock situation in which the entire filter graph seizes up, waiting for a lock that will never be released. Filter developers are strongly encouraged to read “Threads and Critical Sections” under “Writing DirectShow Filters” in the DirectX SDK documentation.

CPushPin::UpdateFromSeek强制filter graph的清空，每次源filter执行查找操作时都会要进行清空。缓存区清空操作分成四步。下游的pin调用DeliverBeginFlush时，清空开始。接着停止流线程，挂起整个filter graph的缓存操作。最后调用DeliverEndFlush; 它用来设置下游filter接收新的媒体本校。然后重新启动流线程。当重启后，调用CPushPin::OnThreadStartPlay并且任何和filter启动相关的操作都要在这里执行。新的启动，停止和流的码率值都被传送到下游。如果filter对线程做了任何复杂的工作，就很容易死锁导致整个filter graph都冻结，等待一个永不释放的锁。Filter的开发强烈要求读DirectX SDK文档中Writing DirectShow Filters 下下的Threads and Critical Sections。

 

When the start position of the stream changes, CPushPin::ChangeStart is invoked. This method resets the stream time to zero (the current time, relatively, as the stream time counts upward while the filter runs) and changes the source time to the requested start time. This translates into a new frame number, which is calculated. CPushPin::UpdateFromSeek is called at the end of the routine so that any buffers in the filter graph can be flushed to make way for the new stream data.

当流的起始位置改变时，就激活了CPushPin::ChangeStart，这个方法重设流时间到零并改变源时间到要求的启动时间。这样就转换到了经过计算的新帧号。在例程的最后，CPushPin::UpdateFromSeek被调用，使得filter graph中的所有缓存区都被清空以接收新的流数据。

 

When the filter receives a seek command that resets the stop position of the stream, CPushPin::ChangeStop is invoked. This method checks to see whether the new stop time is past the current time. If it is, the graph is flushed with a call to CPushPin::UpdateFromSeek.

当filter收到重设流的停止位置的查找命令时，就激活了CPushPin::ChangeStop，这个方法检查是否有新的停止时间超过了当前时间，如果是，graph就调用CPushPin::UpdateFromSeek来清空。

 

The playback rate of a stream can be adjusted through a call to the IMediaSeeking interface. The playback rate of the PushSource filter, for example, is 30 frames a second (fps), but it could be adjusted to 15 or 60 fps or any other value. When the playback rate is changed, CPushPin::SetRate is invoked. It modifies the internal variable containing the playback rate and then calls CPushPin::UpdateFromSeek to flush the downstream filters. It’s not necessary to override CSourceSeeking::SetRate, but we’ve overridden it here in CPushPin because this version includes a parameter check on the rate value to ensure its validity.

流找回放速率可以能过调用IMediaSeeking来调整。PushSource filter的回放速率是30fps，但是它可以调整到15到60fps或任何其它值。当回放速率改变时，就激活了CPushPin::SetRate。它改变了包含回放速率的内部变量然后调用CPushPin::UpdateFromSeek来清空下游filter。没有必要重写CSourceSeeking::SetRate。但在CPushPin这个例子中重写了这个方法是因为这个版本包含了参数检查以确保速率的有效性。

 

All the routines discussed thus far handle seeking from a base of the DirectShow reference time, in units of 100 nanoseconds. DirectShow filters can also support other time formats. This can be handy when dealing with video, which is parceled out in units of frames, or fields. A source filter doesn’t need to implement multiple time formats for seeking, but the PushSource filter does. These CPushPin methods, overridden from CSourceSeeking, allow the PushSource filter to work in a time base of frames, as shown in the following code:

所有处理查找的程序都是基于DS的参数时钟，它的单位是100ns。DS filter也可以支持其它时钟格式。处理视频时还是很麻烦的，因为它是以帧或场作为单位。源filter并不需要为了查找而实现多个时钟格式，但是PushSource实现了。CPushPin方法覆盖了CSourceSeeking，从而允许PushSource filter基于帧工作，代码如下：

点击(此处)折叠或打开

1. STDMETHODIMP CPushPin::SetTimeFormat(const GUID *pFormat)
   
2. {
   
3.   CAutoLock cAutoLock(m_pFilter->pStateLock());
   
4.   CheckPointer(pFormat, E_POINTER);
   
5.   if (m_pFilter->IsActive())
   
6.   {
   
7.     // Cannot switch formats while running.
   
8.     return VFW_E_WRONG_STATE;
   
9.   }
   
10. 
    
11.   if (S_OK != IsFormatSupported(pFormat))
    
12.   {
    
13.     // We don't support this time format.
    
14.     return E_INVALIDARG;
    
15.   }
    
16.   m_TimeFormat = *pFormat;
    
17.   return S_OK;
    
18. }
    
19. 
    
20. STDMETHODIMP CPushPin::GetTimeFormat(GUID *pFormat)
    
21. {
    
22.   CAutoLock cAutoLock(m_pFilter->pStateLock());
    
23.   CheckPointer(pFormat, E_POINTER);
    
24.   *pFormat = m_TimeFormat;
    
25.   return S_OK;
    
26. }
    
27. 
    
28. STDMETHODIMP CPushPin::IsUsingTimeFormat(const GUID *pFormat)
    
29. {
    
30.   CAutoLock cAutoLock(m_pFilter->pStateLock());
    
31.   CheckPointer(pFormat, E_POINTER);
    
32.   return (*pFormat == m_TimeFormat ? S_OK : S_FALSE);
    
33. }
    
34. 
    
35. STDMETHODIMP CPushPin::IsFormatSupported( const GUID * pFormat)
    
36. {
    
37.   CheckPointer(pFormat, E_POINTER);
    
38.   if (*pFormat == TIME_FORMAT_MEDIA_TIME)
    
39.   {
    
40.     return S_OK;
    
41.   }
    
42.   else if (*pFormat == TIME_FORMAT_FRAME)
    
43.   {
    
44.     return S_OK;
    
45.   }
    
46.   else
    
47.   {
    
48.     return S_FALSE;
    
49.   }
    
50. }
    
51. 
    
52. STDMETHODIMP CPushPin::QueryPreferredFormat(GUID *pFormat)
    
53. {
    
54.   CheckPointer(pFormat, E_POINTER);
    
55.   *pFormat = TIME_FORMAT_FRAME;     // Doesn't really matter which we prefer
    
56.   return S_OK;
    
57. }
    
58. 
    
59. STDMETHODIMP CPushPin::ConvertTimeFormat(
    
60.     LONGLONG *pTarget,           // Receives the converted time value.
    
61.     const GUID *pTargetFormat,   // Specifies the target format for the conversion.
62.     LONGLONG Source,             // Time value to convert.
    
63.     const GUID *pSourceFormat)   // Time format for the Source time.
    
64. {
    
65.   CheckPointer(pTarget, E_POINTER);
    
66. 
    
67.   // Either of the format GUIDs can be NULL,
    
68.   // which means "use the current time format"
    
69.   GUID TargetFormat, SourceFormat;
    
70.   TargetFormat = (pTargetFormat == NULL ? m_TimeFormat : *pTargetFormat );
    
71.   SourceFormat = (pSourceFormat == NULL ? m_TimeFormat : *pSourceFormat );
    
72. 
    
73.   if (TargetFormat == TIME_FORMAT_MEDIA_TIME)
    
74.   {
    
75.     if (SourceFormat == TIME_FORMAT_FRAME)
    
76.     {
    
77.       *pTarget = FrameToTime(Source);
    
78.       return S_OK;
    
79.     }
    
80. 
    
81.     if (SourceFormat == TIME_FORMAT_MEDIA_TIME)
    
82.     {
    
83.       // no-op
    
84.       *pTarget = Source;
    
85.       return S_OK;
    
86.     }
    
87.     return E_INVALIDARG; // Invalid source format.
    
88.   }
    
89. 
    
90.   if (TargetFormat == TIME_FORMAT_FRAME)
    
91.   {
    
92.     if (SourceFormat == TIME_FORMAT_MEDIA_TIME)
    
93.     {
    
94.       *pTarget = TimeToFrame(Source);
    
95.       return S_OK;
    
96.     }
    
97. 
    
98.     if (SourceFormat == TIME_FORMAT_FRAME)
    
99.     {
    
100.       // no-op
     
101.       *pTarget = Source;
     
102.       return S_OK;
     
103.     }
     
104.     return E_INVALIDARG; // Invalid source format.
     
105.   }
     
106.   return E_INVALIDARG;   // Invalid target format.
     
107. }
     
108. 
     
109. STDMETHODIMP CPushPin::SetPositions(
     
110.                 LONGLONG *pCurrent, // New current position (can be NULL!) 
     
111.                 DWORD CurrentFlags,
     
112.                 LONGLONG *pStop,    // New stop position (can be NULL!)
     
113.                 DWORD StopFlags)
     
114. {
     
115.   HRESULT hr;
     
116.   if (m_TimeFormat == TIME_FORMAT_FRAME)
     
117.   {
     
118.     REFERENCE_TIME rtCurrent = 0, rtStop = 0;
     
119.     if (pCurrent)
     
120.     {
     
121.       rtCurrent = FrameToTime(*pCurrent);
     
122.     }
     
123. 
     
124.     if (pStop)
     
125.     {
     
126.       rtStop = FrameToTime(*pStop);
     
127.     }
     
128. 
     
129.     hr = CSourceSeeking::SetPositions(&rtCurrent, CurrentFlags,
     
130.                                       &rtStop, StopFlags);
     
131. 
     
132.     if (SUCCEEDED(hr))
     
133.     {
     
134.       // The AM_SEEKING_ReturnTime flag
     
135.       // means the caller wants the input times
     
136.       // converted to the current time format.
     
137.       if (pCurrent && (CurrentFlags & AM_SEEKING_ReturnTime))
     
138.       {
     
139.         *pCurrent = rtCurrent;
     
140.       }
     
141. 
     
142.       if (pStop && (StopFlags & AM_SEEKING_ReturnTime))
     
143.       {
     
144.         *pStop = rtStop;
     
145.       }
     
146.     }
     
147.   }
     
148.   else
     
149.   {
     
150.     // Simple pass thru'
     
151.     hr = CSourceSeeking::SetPositions(pCurrent, CurrentFlags,
     
152.     pStop, StopFlags);
     
153.   }
     
154.   return hr;
     
155. }
     
156. 
     
157. STDMETHODIMP CPushPin::GetDuration(LONGLONG *pDuration)
     
158. {
     
159.   HRESULT hr = CSourceSeeking::GetDuration(pDuration);
     
160.   if (SUCCEEDED(hr))
     
161.   {
     
162.     if (m_TimeFormat == TIME_FORMAT_FRAME)
     
163.     {
     
164.       *pDuration = TimeToFrame(*pDuration);
     
165.     }
     
166.   }
     
167.   return S_OK;
     
168. }
     
169. 
     
170. STDMETHODIMP CPushPin::GetStopPosition(LONGLONG *pStop)
     
171. {
     
172.   HRESULT hr = CSourceSeeking::GetStopPosition(pStop);
     
173.   if (SUCCEEDED(hr))
     
174.   {
     
175.     if (m_TimeFormat == TIME_FORMAT_FRAME)
     
176.     {
     
177.       *pStop = TimeToFrame(*pStop);
     
178.     }
     
179.   }
     
180.   return S_OK;
     
181. }

A request to change the time format can be set with a call to CPushPin::SetTimeFormat; the passed parameter is a GUID, which describes the time format. (The list of time format GUIDs can be found in the DirectX SDK documentation.) If CPushPin::IsSupportedFormat reports that the time format is supported, the format is changed. The two supported formats for CPushPin are TIME_FORMAT_MEDIA_TIME, which is the reference time of 100-nanosecond units, and TIME_FORMAT_FRAME, in which each unit constitutes one video frame.

CPushPin::SetTimeFormat可以用来改变时钟格式。它的参数为GUID,描述了时钟格式。如果CPushPin::IsSupportedFormat报告支持某种时钟格式，那么这个格式就改好了。CPushPin支持两种格式：TIME_FORMAT_MEDIA_TIME，100ns为单位。TIME_FORMAT_FRAME,，以视频帧为单位。

 

Conversions between time formats are performed in CPushPin::ConvertTimeFormat. Because PushSource supports two time formats, the routine must perform conversions between TIME_FORMAT_MEDIA_TIME and TIME_FORMAT_FRAME. CPushPin::GetDuration, CPushPin::GetStopPosition, and CPushPin::SetPositions are overridden because their return values must reflect the current time format. (Imagine what would happen if the Filter Graph Manager, expecting frames, was informed there were 300,000,000 of them!)

两种时钟格式在CPushPin::ConvertTimeFormat都能执行。因为PushSource都支持也只支持TIME_FORMAT_MEDIA_TIME和TIME_FORMAT_FRAME这两种。CPushPin::GetDuration, CPushPin::GetStopPosition, 和CPushPin::SetPositions都要被重写，因为它们的返回值必须反映当前的时钟格式。

 

There’s just a bit more C++ code needed to handle the COM interfaces, which we’ve seen previously in the YUVGray and SampleGrabber filters. When compiled and registered (which should happen automatically), the “Generic Push Source” filter will appear in the list of DirectShow filters in GraphEdit.

这里还有一些C++代码用来处理COM接口，和前面的例子相同的。编译和注册后就能用了。

 

Summary

Source filters are absolutely essential because they generate the media samples that pass through the filter graph until rendered. Most hardware devices don’t need custom DirectShow filters because DirectShow has wrappers to “automagically” make WDM and VFW device drivers appear as filters to DirectShow applications. Other source filters can read data from a file, from a URL, and so forth. Some source filters, such as the PushSource example explored in this chapter, create their own media streams. In large part, control of the filter graph is driven by the source filters it contains. In the implementation of PushSource, we’ve explored how the different operating states of the filter graph are reflected in the design of a source filter. Therefore, a detailed study of source filters reveals how DirectShow executes a filter graph.

源filter肯定是很重要的，因为它们生成媒体样本。