Compartilhar via

Implementando IWICBitmapCodecProgressNotification (Decoder)

  • Artigo

IWICBitmapCodecProgressNotification

Quando um codec está executando uma operação de E/S como CopyPixels em uma imagem grande, pode levar vários segundos ou até minutos para ser concluído. Quando os usuários finais não conseguem interromper uma operação de execução prolongada, eles podem pensar que o aplicativo foi travado. Os usuários geralmente fecham um aplicativo ou até mesmo reiniciam seus computadores, na tentativa de recuperar o controle do computador quando um aplicativo fica sem resposta.

Essa interface permite que um aplicativo especifique uma função de retorno de chamada que o codec pode chamar em intervalos especificados para notificar o chamador sobre o progresso da operação atual. O aplicativo pode usar essa função de retorno de chamada para exibir uma indicação de progresso na interface do usuário para notificar o usuário sobre o status da operação. Se um usuário clicar no botão Cancelar na caixa de diálogo Progresso , o aplicativo retornará WINCODEC_ERR_ABORTED da função de retorno de chamada. Quando isso acontece, o codec deve cancelar a operação especificada e propagar esse HRESULT de volta para o chamador do método que estava executando a operação.

Essa interface deve ser implementada em sua classe de decodificador no nível do contêiner.

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

RegisterProgressNotification

RegisterProgressNotification é invocado por um aplicativo para registrar uma função de retorno de chamada que o codec pode chamar em intervalos especificados. O primeiro parâmetro, pfnProgressNotification, é um ponteiro para a função de retorno de chamada que o codec deve chamar em intervalos regulares.

O parâmetro pvData aponta para algum objeto que o chamador deseja que o codec passe de volta para a função de retorno de chamada sempre que a função de retorno de chamada for invocada. Esse objeto pode ser qualquer coisa e não tem nenhum significado específico para o codec.

O parâmetro dwProgressFlags especifica quando o codec deve chamar a função de retorno de chamada. Uma função OR pode ser executada com duas enumerações para esse parâmetro. A enumeração WICProgressOperation especifica se a função de retorno de chamada deve ser chamada durante a decodificação (WICProgressOperationCopyPixels), codificação (WICProgerssOperationWritePixels) ou ambas (WICProgressOperationAll).

enum WICProgressOperation
{
   WICProgressOperationCopyPixels,
   WICProgerssOperationWritePixels,
   WICProgressOperationAll      
};

O codec deve chamar a função de retorno de chamada em intervalos regulares durante toda a operação, mas o chamador pode especificar determinados requisitos. A enumeração WICProgressNotification indica em que ponto da operação chamar a função de retorno de chamada. Se o chamador especificar WICProgressNotificationBegin, você deverá chamá-lo no início da operação (0.0). Se o chamador não especificar isso, ele será opcional. Da mesma forma, se o chamador especificar WICProgerssNotificationEnd, você deverá chamá-la quando a operação for concluída (1.0). Se o chamador especificar WICProgressNotificationAll, você deverá chamá-lo no início e no final, bem como em intervalos regulares durante toda a operação. O chamador também pode especificar WICProgerssNotificationFrequent, o que indica que ele deseja ser chamado novamente em intervalos frequentes, talvez após cada duas linhas de verificação. (Um chamador geralmente usará esse sinalizador apenas para uma imagem muito grande.) Caso contrário, você geralmente deve chamar de volta em intervalos de aproximadamente 10% de incrementos do número total de linhas de verificação a serem processadas.

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

Somente uma função de retorno de chamada por vez pode ser registrada para uma instância específica de decodificador ou codificador. Se um aplicativo chamar RegisterProgressNotification mais de uma vez, substitua a função de retorno de chamada registrada anteriormente pela nova. Para cancelar um registro de retorno de chamada, um chamador definirá o parâmetro pfnProgressNotification como NULL.

PFNProgressNotification

PFNProgressNotification é a função de retorno de chamada com a assinatura a seguir.

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

Quando você invocar a função de retorno de chamada, use o parâmetro pvData para retornar o mesmo pvData especificado pelo aplicativo quando registrou a função de retorno de chamada.

O parâmetro uFrameNum deve indicar o índice do quadro que está sendo processado.

Defina o parâmetro de operação como WICProgressOperationCopyPixels ao decodificar e WICProgressOperationWritePixels durante a codificação.

O parâmetro dblProgress deve ser um número entre 0,0 (o início da operação) e 1,0 (a conclusão da operação). O valor deve refletir a proporção de linhas de verificação já processadas em relação ao número total de linhas de verificação a serem processadas.

Referência

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

Conceitual

Implementando IWICBitmapDecoder

Implementando IWICBitmapSource

Como escrever uma WIC-Enabled CODEC

Visão geral do componente de imagem do Windows