实现 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 参数应指示正在处理的帧的索引。

解码时，将操作参数设置为 WICProgressOperationCopyPixels ，编码时将 WICProgressOperationWritePixels 设置为 WICProgressOperationWritePixels 。

dblProgress 参数应是一个介于操作) 开始 (0.0 和 1.0 之间的数字， (操作) 完成。 该值应反映已处理的扫描行相对于要处理的扫描行总数的比例。

参考

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

概念性

实现 IWICBitmapDecoder

实现 IWICBitmapSource

如何编写WIC-Enabled CODEC

Windows 映像组件概述