Реализация IWICBitmapCodecProgressNotification (декодер)

  • Статья

IWICBitmapCodecProgressNotification

Когда кодек выполняет операцию ввода-вывода, например 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 при кодировании.

Параметр dblProgress должен быть числом в диапазоне от 0,0 (начало операции) до 1,0 (завершение операции). Значение должно отражать долю уже обработанных строк сканирования относительно общего числа обрабатываемых строк сканирования.

Reference

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

Основные понятия

Реализация IWICBitmapDecoder

Реализация IWICBitmapSource

Создание кодека WIC-Enabled

Общие сведения о компоненте обработки образов Windows