使用範例擷取器

發行項
03/18/2025

[與此頁面相關聯的功能，DirectShow是舊版功能。它已被 MediaPlayer、IMFMediaEngine和媒體基礎中的音訊/視訊擷取取代。這些功能已針對 Windows 10 和 Windows 11 進行優化。 Microsoft強烈建議新程式代碼盡可能在媒體 基礎中使用 MediaPlayer、IMFMediaEngine 和 音訊/視訊擷取，而不是 DirectShow。 Microsoft建議使用舊版 API 的現有程式代碼，盡可能改寫成使用新的 API。]

[此 API 不受支持，未來可能會改變或無法使用。]

範例擷取器 濾鏡是一種轉換濾鏡，可用於當數據流通過濾鏡圖表時，擷取媒體樣本。

如果您只想從視訊檔案擷取位圖，使用 Media Detector （MediaDet）物件會比較容易。如需詳細情報，請參閱擷取海報畫面。不過，Sample Grabber 更具靈活性，因為它幾乎可以處理任何媒體類型（請參閱 ISampleGrabber::SetMediaType 查看少數例外），並為應用程式提供更多控制權。

建立 Filter Graph Manager
將範例擷取器新增至篩選圖形
設定媒體類型
建置篩選圖形
執行圖表
擷取範例
範例程式代碼
相關主題

建立 Filter Graph 管理員

若要開始，請建立 Filter Graph Manager，並查詢 IMediaControl 和 IMediaEventEx 介面。

    IGraphBuilder *pGraph = NULL;
    IMediaControl *pControl = NULL;
    IMediaEventEx *pEvent = NULL;


    HRESULT hr = CoCreateInstance(CLSID_FilterGraph, NULL, 
        CLSCTX_INPROC_SERVER,IID_PPV_ARGS(&pGraph));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pControl));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pEvent));
    if (FAILED(hr))
    {
        goto done;
    }

將範例擷取器新增至篩選圖形

建立範例擷取器濾鏡的實例，並將其新增至濾鏡圖形。查詢 ISampleGrabber 介面的範例擷取器篩選。

    IBaseFilter *pGrabberF = NULL;
    ISampleGrabber *pGrabber = NULL;


    // Create the Sample Grabber filter.
    hr = CoCreateInstance(CLSID_SampleGrabber, NULL, CLSCTX_INPROC_SERVER,
        IID_PPV_ARGS(&pGrabberF));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->AddFilter(pGrabberF, L&quot;Sample Grabber&quot;);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGrabberF->QueryInterface(IID_PPV_ARGS(&pGrabber));
    if (FAILED(hr))
    {
        goto done;
    }

設定媒體類型

當您第一次建立範例擷取器時，它沒有慣用的媒體類型。這表示您可以連線到圖形中幾乎任何篩選，但您無法控制它收到的數據類型。因此，在建置圖形的其餘部分之前，您必須呼叫 ISampleGrabber：：SetMediaType 方法來設定 Sample Grabber 的媒體類型。

當範例擷取器連線時，它會比較此媒體類型與其他篩選條件所提供的媒體類型。它檢查的唯一欄位是主要類型、子類型和格式類型。對於其中任何一項，值GUID_NULL表示「接受任何值」。大部分時候，您會想要設定主要類型和子類型。例如，下列程式代碼會指定未壓縮的 24 位 RGB 視訊：

    AM_MEDIA_TYPE mt;
    ZeroMemory(&mt, sizeof(mt));
    mt.majortype = MEDIATYPE_Video;
    mt.subtype = MEDIASUBTYPE_RGB24;

    hr = pGrabber->SetMediaType(&mt);
    if (FAILED(hr))
    {
        goto done;
    }

建置篩選圖形

現在您可以建置篩選圖形的其餘部分。由於範例擷取器只會使用您指定的媒體類型進行連線，因此當您建置圖形時，這可讓您利用 Filter Graph Manager 的 Intelligent Connect 機制。

例如，如果您指定了未壓縮的視訊，您可以將來源篩選連接到範例擷取器，而 Filter Graph 管理員會自動新增檔案剖析器和譯碼器。下列範例使用 ConnectFilters 協助程式函式，此函式列在 Connect Two Filters中：

    IBaseFilter *pSourceF = NULL;
    IEnumPins *pEnum = NULL;
    IPin *pPin = NULL;


    hr = pGraph->AddSourceFilter(pszVideoFile, L&quot;Source&quot;, &pSourceF);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pSourceF->EnumPins(&pEnum);
    if (FAILED(hr))
    {
        goto done;
    }

    while (S_OK == pEnum->Next(1, &pPin, NULL))
    {
        hr = ConnectFilters(pGraph, pPin, pGrabberF);
        SafeRelease(&pPin);
        if (SUCCEEDED(hr))
        {
            break;
        }
    }

    if (FAILED(hr))
    {
        goto done;
    }

範例擷取器是一個轉換過濾器，因此輸出端口必須連接到另一個過濾器。通常，您可能只是在完成後想要捨棄這些範例。在此情況下，將範例擷取器連接到 Null 轉譯器篩選，這會捨棄它接收的數據。

下列範例會將範例擷取器連接到 Null 渲染篩選器：

    IBaseFilter *pNullF = NULL;


    hr = CoCreateInstance(CLSID_NullRenderer, NULL, CLSCTX_INPROC_SERVER, 
        IID_PPV_ARGS(&pNullF));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->AddFilter(pNullF, L&quot;Null Filter&quot;);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = ConnectFilters(pGraph, pGrabberF, pNullF);
    if (FAILED(hr))
    {
        goto done;
    }

請注意，將範例擷取器放在影片譯碼器和視訊轉譯器之間，可能會大幅損害轉譯效能。範例擷取器是一種就地传递过滤器，這意味著輸出緩衝區與輸入緩衝區相同。針對視訊轉譯，輸出緩衝區可能位於圖形卡片上，相較於主要記憶體中的讀取作業，讀取作業速度會變慢。

執行圖表

範例擷取器會以下列兩種模式的其中一種運作：

緩衝模式會在將範例傳遞至下游之前，先為每個樣本製作一個複本。
回呼模式會在每個範例上叫用應用程式定義的回呼函式。

本文說明緩衝模式。（在使用回呼模式之前，請注意回呼函式必須相當有限。否則，它可以大幅降低效能，甚至造成死結。如需詳細資訊，請參閱 ISampleGrabber：：SetCallback。）若要啟動緩衝模式，請使用 true 值呼叫 ISampleGrabber：：SetBufferSamples 方法。

或者，使用 true值呼叫 ISampleGrabber：：SetOneShot 方法。這會導致範例擷取器在收到第一個媒體範例之後停止，如果您想要從數據流擷取單一畫面格，這會很有用。尋找所需的時間、運行圖表，並等候 EC_COMPLETE 事件。請注意，畫面精確度層級取決於來源。例如，搜尋 MPEG 檔案通常無法達到逐幀精確。

若要儘快執行圖形，請關閉圖形時鐘，如設定圖形時鐘中所述。

下列範例會啟用單次模式和緩衝模式、執行篩選圖形，並等候完成。

    hr = pGrabber->SetOneShot(TRUE);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGrabber->SetBufferSamples(TRUE);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pControl->Run();
    if (FAILED(hr))
    {
        goto done;
    }

    long evCode;
    hr = pEvent->WaitForCompletion(INFINITE, &evCode);

擷取範例

在緩衝模式中，範例擷取器會儲存每個樣本的複本。 ISampleGrabber：：GetCurrentBuffer 方法會將緩衝區複製到呼叫端配置的陣列。若要判斷所需的陣列大小，請先使用陣列位址指標為 NULL 呼叫 GetCurrentBuffer。然後配置陣列，並第二次呼叫方法以複製緩衝區。下列範例顯示這些步驟。

    // Find the required buffer size.
    long cbBuffer;
    hr = pGrabber->GetCurrentBuffer(&cbBuffer, NULL);
    if (FAILED(hr))
    {
        goto done;
    }

    pBuffer = (BYTE*)CoTaskMemAlloc(cbBuffer);
    if (!pBuffer) 
    {
        hr = E_OUTOFMEMORY;
        goto done;
    }

    hr = pGrabber->GetCurrentBuffer(&cbBuffer, (long*)pBuffer);
    if (FAILED(hr))
    {
        goto done;
    }

您必須知道緩衝區中數據的確切格式。若要取得這項資訊，請呼叫 ISampleGrabber：：GetConnectedMediaType 方法。此方法會將格式填入 AM_MEDIA_TYPE 結構。

對於未壓縮的視訊串流，格式資訊會包含在 VIDEOINFOHEADER 結構中。下列範例示範如何取得未壓縮視訊數據流的格式資訊。

    // Examine the format block.
    if ((mt.formattype == FORMAT_VideoInfo) && 
        (mt.cbFormat >= sizeof(VIDEOINFOHEADER)) &&
        (mt.pbFormat != NULL)) 
    {
        VIDEOINFOHEADER *pVih = (VIDEOINFOHEADER*)mt.pbFormat;

        hr = WriteBitmap(pszBitmapFile, &pVih->bmiHeader, 
            mt.cbFormat - SIZE_PREHEADER, pBuffer, cbBuffer);
    }
    else 
    {
        // Invalid format.
        hr = VFW_E_INVALIDMEDIATYPE; 
    }

注意

範例擷取器不支援 VIDEOINFOHEADER2。

範例程序代碼

以下是先前範例的完整程序代碼。

注意

此範例會使用 SafeRelease 函式來釋放介面指標。

#include <windows.h>
#include <dshow.h>
#include "qedit.h"

template <class T> void SafeRelease(T **ppT)
{
    if (*ppT)
    {
        (*ppT)->Release();
        *ppT = NULL;
    }
}



HRESULT WriteBitmap(PCWSTR, BITMAPINFOHEADER*, size_t, BYTE*, size_t);

HRESULT GrabVideoBitmap(PCWSTR pszVideoFile, PCWSTR pszBitmapFile)
{
    IGraphBuilder *pGraph = NULL;
    IMediaControl *pControl = NULL;
    IMediaEventEx *pEvent = NULL;
    IBaseFilter *pGrabberF = NULL;
    ISampleGrabber *pGrabber = NULL;
    IBaseFilter *pSourceF = NULL;
    IEnumPins *pEnum = NULL;
    IPin *pPin = NULL;
    IBaseFilter *pNullF = NULL;

    BYTE *pBuffer = NULL;

    HRESULT hr = CoCreateInstance(CLSID_FilterGraph, NULL, 
        CLSCTX_INPROC_SERVER,IID_PPV_ARGS(&pGraph));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pControl));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->QueryInterface(IID_PPV_ARGS(&pEvent));
    if (FAILED(hr))
    {
        goto done;
    }

    // Create the Sample Grabber filter.
    hr = CoCreateInstance(CLSID_SampleGrabber, NULL, CLSCTX_INPROC_SERVER,
        IID_PPV_ARGS(&pGrabberF));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->AddFilter(pGrabberF, L&quot;Sample Grabber&quot;);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGrabberF->QueryInterface(IID_PPV_ARGS(&pGrabber));
    if (FAILED(hr))
    {
        goto done;
    }

    AM_MEDIA_TYPE mt;
    ZeroMemory(&mt, sizeof(mt));
    mt.majortype = MEDIATYPE_Video;
    mt.subtype = MEDIASUBTYPE_RGB24;

    hr = pGrabber->SetMediaType(&mt);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->AddSourceFilter(pszVideoFile, L&quot;Source&quot;, &pSourceF);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pSourceF->EnumPins(&pEnum);
    if (FAILED(hr))
    {
        goto done;
    }

    while (S_OK == pEnum->Next(1, &pPin, NULL))
    {
        hr = ConnectFilters(pGraph, pPin, pGrabberF);
        SafeRelease(&pPin);
        if (SUCCEEDED(hr))
        {
            break;
        }
    }

    if (FAILED(hr))
    {
        goto done;
    }

    hr = CoCreateInstance(CLSID_NullRenderer, NULL, CLSCTX_INPROC_SERVER, 
        IID_PPV_ARGS(&pNullF));
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGraph->AddFilter(pNullF, L&quot;Null Filter&quot;);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = ConnectFilters(pGraph, pGrabberF, pNullF);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGrabber->SetOneShot(TRUE);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGrabber->SetBufferSamples(TRUE);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pControl->Run();
    if (FAILED(hr))
    {
        goto done;
    }

    long evCode;
    hr = pEvent->WaitForCompletion(INFINITE, &evCode);

    // Find the required buffer size.
    long cbBuffer;
    hr = pGrabber->GetCurrentBuffer(&cbBuffer, NULL);
    if (FAILED(hr))
    {
        goto done;
    }

    pBuffer = (BYTE*)CoTaskMemAlloc(cbBuffer);
    if (!pBuffer) 
    {
        hr = E_OUTOFMEMORY;
        goto done;
    }

    hr = pGrabber->GetCurrentBuffer(&cbBuffer, (long*)pBuffer);
    if (FAILED(hr))
    {
        goto done;
    }

    hr = pGrabber->GetConnectedMediaType(&mt);
    if (FAILED(hr))
    {
        goto done;
    }

    // Examine the format block.
    if ((mt.formattype == FORMAT_VideoInfo) && 
        (mt.cbFormat >= sizeof(VIDEOINFOHEADER)) &&
        (mt.pbFormat != NULL)) 
    {
        VIDEOINFOHEADER *pVih = (VIDEOINFOHEADER*)mt.pbFormat;

        hr = WriteBitmap(pszBitmapFile, &pVih->bmiHeader, 
            mt.cbFormat - SIZE_PREHEADER, pBuffer, cbBuffer);
    }
    else 
    {
        // Invalid format.
        hr = VFW_E_INVALIDMEDIATYPE; 
    }

    FreeMediaType(mt);

done:
    CoTaskMemFree(pBuffer);
    SafeRelease(&pPin);
    SafeRelease(&pEnum);
    SafeRelease(&pNullF);
    SafeRelease(&pSourceF);
    SafeRelease(&pGrabber);
    SafeRelease(&pGrabberF);
    SafeRelease(&pControl);
    SafeRelease(&pEvent);
    SafeRelease(&pGraph);
    return hr;
};

// Writes a bitmap file
//  pszFileName:  Output file name.
//  pBMI:         Bitmap format information (including pallete).
//  cbBMI:        Size of the BITMAPINFOHEADER, including palette, if present.
//  pData:        Pointer to the bitmap bits.
//  cbData        Size of the bitmap, in bytes.

HRESULT WriteBitmap(PCWSTR pszFileName, BITMAPINFOHEADER *pBMI, size_t cbBMI,
    BYTE *pData, size_t cbData)
{
    HANDLE hFile = CreateFile(pszFileName, GENERIC_WRITE, 0, NULL, 
        CREATE_ALWAYS, 0, NULL);
    if (hFile == NULL)
    {
        return HRESULT_FROM_WIN32(GetLastError());
    }

    BITMAPFILEHEADER bmf = { };

    bmf.bfType = &#39;MB&#39;;
    bmf.bfSize = cbBMI+ cbData + sizeof(bmf); 
    bmf.bfOffBits = sizeof(bmf) + cbBMI; 

    DWORD cbWritten = 0;
    BOOL result = WriteFile(hFile, &bmf, sizeof(bmf), &cbWritten, NULL);
    if (result)
    {
        result = WriteFile(hFile, pBMI, cbBMI, &cbWritten, NULL);
    }
    if (result)
    {
        result = WriteFile(hFile, pData, cbData, &cbWritten, NULL);
    }

    HRESULT hr = result ? S_OK : HRESULT_FROM_WIN32(GetLastError());

    CloseHandle(hFile);

    return hr;
}

使用 DirectShow 編輯服務

共用方式為

使用範例擷取器

建立 Filter Graph 管理員

將範例擷取器新增至篩選圖形

設定媒體類型

建置篩選圖形

執行圖表

擷取範例

範例程序代碼

意見反應

其他資源

共用方式為

使用範例擷取器

建立 Filter Graph 管理員

將範例擷取器新增至篩選圖形

設定媒體類型

建置篩選圖形

執行圖表

擷取範例

範例程序代碼

相關主題

意見反應

其他資源