實作 IWICBitmapCodecProgressNotification (解碼器)

  • 發行項

IWICBitmapCodecProgressNotification

當編解碼器在大型映射上執行 I/O 作業，例如 CopyPixels 時，可能需要幾秒鐘或甚至幾分鐘才能完成。 當使用者無法中斷長時間執行的作業時，他們可能會認為應用程式已無回應。 使用者通常會關閉應用程式，或甚至重新開機電腦，嘗試在應用程式沒有回應時重新取得其電腦的控制權。

此介面可讓應用程式指定回呼函式，讓編解碼器可以依指定的間隔呼叫，以通知呼叫端目前作業的進度。 應用程式可以使用這個回呼函式，在使用者介面中顯示進度的指示，以通知使用者作業的狀態。 如果使用者按一下 [進度] 對話方塊上的 [取消] 按鈕，應用程式會從回呼函式傳回WINCODEC_ERR_ABORTED。 發生這種情況時，編解碼器必須取消指定的作業，並將這個 HRESULT 傳播回執行作業之方法的呼叫端。

此介面應該在您的容器層級解碼器類別上實作。

interface IWICBitmapCodecProgressNotification : public IUnknown
{
    HRESULT RegisterProgressNotification ( 
        PFNProgressNotification pfnProgressNotification,
        LPVOID pvData,
        DWORD dwProgressFlags );
}

RegisterProgressNotification

RegisterProgressNotification 是由應用程式叫用，以註冊編解碼器可以依指定間隔呼叫的回呼函式。 第一個參數 pfnProgressNotification是編解碼器應該定期呼叫的回呼函式指標。

pvData參數指向呼叫端希望編解碼器在叫用回呼函式時傳回回回呼函式的某些物件。 這個物件可能完全是任何專案，而且對編解碼器沒有特別的重要性。

dwProgressFlags參數會指定編解碼器何時應該呼叫回呼函式。 您可以使用此參數的兩個列舉來執行 OR 函式。 WICProgressOperation列舉會指定在解碼 (WICProgressOperationCopyPixels) 、編碼 (WICProgerssOperationWritePixels) 期間呼叫回呼函式，還是 (WICProgressOperationAll) 。

enum WICProgressOperation
{
   WICProgressOperationCopyPixels,
   WICProgerssOperationWritePixels,
   WICProgressOperationAll      
};

編解碼器應該在作業期間定期呼叫回呼函式，但呼叫端可能會指定特定需求。 WICProgressNotification列舉表示呼叫回呼函式的作業中哪個時間點。 如果呼叫端指定 WICProgressNotificationBegin，您必須在作業開頭呼叫它， (0.0) 。 如果呼叫端未指定此專案，則為選擇性。 同樣地，如果呼叫端指定 WICProgerssNotificationEnd，您必須在作業完成時呼叫它 (1.0) 。 如果呼叫端指定 WICProgressNotificationAll，您必須在開頭和結尾呼叫它，以及整個作業的定期間隔。 呼叫端也可以指定 WICProgerssNotificationFrequent，這表示他們想要以頻繁的間隔回呼，或許會在每幾行掃描行之後呼叫。 (呼叫端通常會將此旗標用於非常大的影像。) 否則，您通常應該以大約 10% 遞增的掃描行總數間隔來回呼。

enum WICProgressNotification
{
   WICProgressNotificationBegin,
   WICProgerssNotificationEnd,
   WICProgerssNotificationFrequent,
   WICProgressNotificationAll
};

一次只能註冊一個回呼函式給特定的解碼器或編碼器實例。 如果應用程式多次呼叫 RegisterProgressNotification ，請將先前註冊的回呼函式取代為新的回呼函式。 若要取消回呼註冊，呼叫端會將 pfnProgressNotification 參數設定為 Null。

PFNProgressNotification

PFNProgressNotification 是具有下列簽章的回呼函式。

typedef HRESULT (*PFNProgressNotification) ( 
   LPVOID pvData,
   ULONG uFrameNum,
   WICProgressOperation operation,
   double dblProgress );

當您叫用回呼函式時，請使用 pvData 參數來傳回應用程式註冊回呼函式時所指定的相同 pvData 。

uFrameNum參數應該會指出正在處理的框架索引。

在編碼時，將 operation 參數設定為 WICProgressOperationCopyPixels 和 WICProgressOperationWritePixels 。

dblProgress參數應該是介於 0.0 (作業開頭) 和 1.0 之間的數位， (作業完成) 。 此值應該反映已處理之掃描行相對於所要處理的掃描行總數的比例。

參考

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

概念

實作 IWICBitmapDecoder

實作 IWICBitmapSource

如何撰寫WIC-Enabled CODEC

Windows 映像處理元件概觀