Media Foundation学习笔记（四）Media Foundation的架构 Platform API

Media Foundation Platform API

 

初始化

HRESULT hr = MFStartup(MF_VERSION);

注意：如果应用程序编译时使用的和系统上Media Foundation的dll不匹配的头文件，MFStartup会返回MF_E_BAD_STARTUP_VERSION错误！

 

MFShutdown();

 

异步方法

在Media Foundation中，大部分操作是使用的异步方式。总所周知，异步操作可以提升性能。一个异步操作在Media Foundation中是用Beginxxx和Endxxx开头字符定义的一对方法，这2个函数定义了流上的一个异步操作。

Beginxxx方法总是包含2个参数：一个IMFAsyncCallback接口对象和一个可选的状态对象。应用程序对流对象调用Beginxxx方法成功后，流对象执行完成会调用这个IMFAsyncCallback接口对象的IMFAsyncCallback::Invoke(IMFAsyncResult* pResult)方法通知应用程序，应用程序应该在IMFAsyncCallback接口对象的Invoke方法被调用后，在Invoke方法里面或者其他线程里面调用Endxxx方法。通常要将在Invoke方法中收到的IMFAsyncResult对象指针作为参数传给Endxxx方法。

Beginxxx方法如果返回一个失败代码，则回调函数不会被流对象调用。

Endxxx方法返回异步操作是成功还是失败的结果。

IMFAsyncCallback::Invoke方法是被另外的线程调用的，应用程序要保证Invoke中的代码是线程安全的。Invoke方法中不要阻塞，不然可能会阻塞流的Pipeline。

 

CMyCallback展现了如何实现IMFAsyncCallback接口：

#include <shlwapi.h>

class CAsyncCallback : public IMFAsyncCallback 
{
public:
    CAsyncCallback () : m_cRef(1) { }
    virtual ~CAsyncCallback() { }

    STDMETHODIMP QueryInterface(REFIID riid, void** ppv)
    {
        static const QITAB qit[] = 
        {
            QITABENT(CAsyncCallback, IMFAsyncCallback),
            { 0 }
        };
        return QISearch(this, qit, riid, ppv);
    }

    STDMETHODIMP_(ULONG) AddRef()
    {
        return InterlockedIncrement(&m_cRef);
    }
    STDMETHODIMP_(ULONG) Release()
    {
        long cRef = InterlockedDecrement(&m_cRef);
        if (cRef == 0)
        {
            delete this;
        }
        return cRef;
    }

    STDMETHODIMP GetParameters(DWORD* pdwFlags, DWORD* pdwQueue)
    {
        // Implementation of this method is optional.
        return E_NOTIMPL;
    }

    STDMETHODIMP Invoke(IMFAsyncResult* pAsyncResult) = 0;
    // TODO: Implement this method. 

    // Inside Invoke, IMFAsyncResult::GetStatus to get the status.
    // Then call the EndX method to complete the operation. 

private:
    long    m_cRef;
};

class CMyCallback : public CAsyncCallback
{
    HANDLE m_hEvent;
    IMFByteStream *m_pStream;

    HRESULT m_hrStatus;
    ULONG   m_cbRead;

public:

    CMyCallback(IMFByteStream *pStream, HRESULT *phr) 
        : m_pStream(pStream), m_hrStatus(E_PENDING), m_cbRead(0)
    {
        *phr = S_OK;

        m_pStream->AddRef();

        m_hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

        if (m_hEvent == NULL)
        {
            *phr = HRESULT_FROM_WIN32(GetLastError());
        }
    }
    ~CMyCallback()
    {
        m_pStream->Release();
        CloseHandle(m_hEvent);
    }

    HRESULT WaitForCompletion(DWORD msec)
    {
        DWORD result = WaitForSingleObject(m_hEvent, msec);

        switch (result)
        {
        case WAIT_TIMEOUT:
            return E_PENDING;

        case WAIT_ABANDONED:
        case WAIT_OBJECT_0:
            return m_hrStatus;

        default:
            return HRESULT_FROM_WIN32(GetLastError());
        }
    }

    ULONG   GetBytesRead() const { return m_cbRead; }

    STDMETHODIMP Invoke(IMFAsyncResult* pResult)
    {
        m_hrStatus = m_pStream->EndRead(pResult, &m_cbRead);

        SetEvent(m_hEvent);

        return S_OK;
    }
};

Work Queues

Work Queues中的Work Items都是实现了IMFAsyncCallback接口的对象，Work Queue拥有一个线程不断从Work Queue取出Work Item并分发它们。

Media Foundation创建了几个标准的Work Queues，称为“Platform work queues”。应用程序可以自己创建Work Queues，称为“Private work queues”。Work Queue用标识符来识别，例如，MFASYNC_CALLBACK_QUEUE_TIMER。

 

创建Work Queue：MFAllocateWorkQueue。

 

添加Work Item：MFPutWorkItem和MFPutItemEx。

 

添加定时执行的 Work Item：MFC ScheduledWorkItem和MFC ScheduledWorkItemEx。定时执行的Work Item总是使用标识符是MFASYNC_CALLBACK_QUEUE_TIMER的“Platform work queues”。

取消定时执行的Work Item：MFCancelWorkItem。

 

添加周期执行的回调：MFAddPeriodicCallback。定时周期是固定的不能被改变，大约是10毫秒，可以通过MFGetTimerPeriodicity获取精确的间隔。周期执行的回调总是使用标识符是MFASYNC_CALLBACK_QUEUE_TIMER的“Platform work queues”。注意，不像其他的Work Item，周期执行的回调不使用IMFAsyncCallbak接口，而是使用函数指针MFPERIODICCALLBACK。

 

取消周期执行的回调：MFRemovePeriodicCallback。

 

如果有超过一个的线程或组件共享Work Queue，需要使用MFLockWorkQueue和MFUnlockWorkQueue来为Work Queue加锁（防止Work Queue被platform释放，该加锁实际是addref，并不会导致第二次调用MFLockQorkQueue阻塞）和解锁。注意：MFAllocateWorkQueue中自动调用了一次MFLockQWorkQueue，因此，MFAllocateWorkQueue后必须要出现一次MFUnlockWorkQueue。

 

使用Work Queue的例子：

DWORD idWorkQueue = 0;
HRESULT hr = S_OK;

// Create a new work queue.
hr = MFAllocateWorkQueue(&idWorkQueue);

// Put an item on the queue.
if (SUCCEEDED(hr))
{
    hr = MFPutWorkItem(idWorkQueue, pCallback, NULL);
}

// Wait for the callback to be invoked.
if (SUCCEEDED(hr))
{
    WaitForSingleObject(hEvent, INFINITE);
}

// Release the work queue.
if (SUCCEEDED(hr))
{
    hr = MFUnlockWorkQueue(idWorkQueue);
}

MFShutdown会自动关闭Work Queues的线程，所以应用程序需要在调用MFShutDown之前确保Work Queues占用的资源都被释放，否则会有内存泄露。如果在调用MFShutDown之前调用了MFLockPlatform，则MFShutDown不会马上关闭Work Queues的资源，而会等等几百毫秒，再关闭。调用MFLockPlatform，然后释放资源，释放资源后，需要调用MFUnlockPlatform。IMFAsyncResult接口的默认实现是，当IMFAsyncResult接口对象被创建的时候会自动锁住Media Foundation Platform，当IMFAsyncResult接口对象被释放的时候自动解锁platform，如果自己实现IMFAsyncResult接口，则需要手动调用MFLockPlatform和MFUnlockPlatform来锁住platfrom。

 

MFC ScheduledWorkItem和MFC ScheduledWorkItemEx的参数是负值，单位是毫秒，例如：设定一个5秒后执行的回调，参数是-5000。

 

Media Event Generators

对象使用events来通知异步操作的完成，或将对象状态相关的改变通知应用程序。

 

如果对象要发送时间，就需要暴露IMFMediaEventGenerator接口。应用程序使用以下2种方式查询event：

1)       IMFMediaEventGenerator::GetEvent，这个方法是同步方法。如果对象的event队列中有event，则立即返回，如果没有，则阻塞或者返回失败，是否阻塞还是返回失败依传入的参数而定；

2)       IMFMediaEventGenerator::BeginGetEvent，这个方法是异步方法。像前面讲的，提供一个IMFAsyncCallback接口，Invoke被调用后，调用EndGetEvent方法。

 

Event对象提供IMFMediaEvent接口。IMFMediaEvent从IMFAttributes继承。

 

Event对象队列：MFCreateEventQueue。

Event对象队列接口：IMFMediaEventQueue。

添加Event对象：IMFMediaEventQueue::QueueEvent、IMFMediaEventQueue::QueueEventParamVar、IMFMediaEventQueue::QueueEventParamUnk。

 

服务接口

在Media Foundataion中，有些接口不能通过QueryInterface获取，而只能通过IMFGetService::GetService获取。IMFGetService::GetService接收服务标识符的GUID，返回服务对象的接口指针。不同于QueryInterface，IMFGetService::GetService获取的对象是另一个对象而不是被调用对象。例如，在DShow中使用Enhanced Video Render就只能使用IMFGetService::GetService获取IMFVideoDisplayControl指针来设置播放窗口。

 

Activation对象

Activation对象用于创建其他对象，有点类似于类工厂。Activation对象暴露IMFActivate接口。

Activation对象让应用可以延迟创建目标对象。应用创建对象前可以通过检查Activation对象的属性来获取目标对象的信息。Activation对象也可以被序列化，这就使得可以在其他进程创建目标对象。

创建和销毁目标对象：IMFActivate::ActivateObject和IMFActivate::ShutdownObject。

Activation对象能拥有属性，IMFActivate接口从IMFAttributes接口继承。一些activation对象属性来配置要创建的对象。

 

PresentationClock

Presentation clock是为Presentation产生时钟时间的对象。Presentation clock中报告的时间称为“Presentation时间”。Presentation中所有的流都被同步到Presentation时间。

接口：IMFPresentationClock、IMFRateControl、IMFTimer和IMFShutdown。

 

Media Sink使用Presentation时间来安排什么时候Render样本。Media Sources和transforms不使用Presentation Clock，因为它们不安排什么时候Deliver样本，而是在Pipeline需要新样本的时候产生样本。

Media Session处理了“创建Presentation Clock”、“选择时间源”等等所有的细节，因此应用程序除了在回放过程中“获取当前的Presentation时间”外，不需要调用Presentation Clock的其他方法。

 

获取当前的Presentation时间使用IMFPresentationClock::GetTime。得到的时间是以100-nano秒（1万个为1毫秒）为单位，因此1秒就是10^7。

 

开始时钟：IMFPresentationClock::Start；

暂停时钟：IMFPresentationClock::Pause；

停止时钟：IMFPresentationClock::Stop；

时钟的跳动步进是1.0（100-nano秒）。要改变步进，获取IMFRateControl接口，使用IMFRateControl::SetRate。

对象可以获取Presentation Clock的状态改变（包括步进的改变）的通知。获取方式：实现IMFClockStateSink接口，调用IMFPresentationClock::AddClockStateSink，取消获取调用IMFPresentationClock::RemoveClockStateSink。

 

创建和销毁Presentation Clock：MFCreatePresentationClock和IMFShutdown::Shutdown。

 

Presentation Clock实际上并不实现一个时钟，它是从其他称为“Presentation时间源”的对象获取时钟时间。时间源对象是一个实现了IMFPresentationTimeSource接口和IMFClockStateSink接口的对象。

 

Presentation Clock对象被创建的时候，并不拥有一个时间源对象，需要调用IMFPresentationClock::SetTimeSources为它设置一个时间源对象。通常，由于音频Renderke可以使用声卡的频率最为时钟，因此音频Render可以作为时间源对象；另外，也可以通过MFCreateSystemTimeSource创建一个基于系统时间的时间源对象，系统时间源可以在没有Media Sink提供时间源的情况下使用。

 

有2中情况Media Sink不遵循Presentation Clock：

1）rateless Media Sink：如写文件。对该类Media Sink调用IMFMediaSink::GetCharacteristic方法返回MEDIASINK_RATELESS。

2）一些Media Sink不能Match Rate的时候。这时调用IMFMediaSink::GetCharacteristic返回MEDIASINK_CANNOT_MATCH_CLOCK。