Partilhar via

Implementar IWICBitmapCodecProgressNotification (Decodificador)

  • 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 longa duração, eles podem pensar que o aplicativo travou. Os usuários geralmente fecham um aplicativo, ou até mesmo reiniciam seus computadores, na tentativa de recuperar o controle do computador quando um aplicativo deixa de responder.

Esta interface permite que um aplicativo especifique uma função de callback que o codec pode chamar em intervalos especificados para notificar o solicitante sobre o progresso da operação em curso. 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 utilizador 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 este HRESULT de volta ao chamador do método que estava a executar a operação.

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

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

RegistarNotificaçãoDeProgresso

RegisterProgressNotification é invocado por uma aplicação para registar uma função de retorno de chamada que o codec pode utilizar 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 devolva à função de retorno de chamada sempre que esta for invocada. Este objeto pode ser qualquer coisa e não tem nenhum significado particular para o codec.

O parâmetro dwProgressFlags especifica quando o codec deve chamar a função de callback. Uma função OR pode ser executada com duas enumerações para este parâmetro. O WICProgressOperation enum 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 callback em intervalos regulares ao longo da operação, mas o chamador pode especificar certos requisitos. A enumeração WICProgressNotification indica em que ponto da operação chamar a função de callback. ** Caso o chamador especifique WICProgressNotificationBegin, deverá chamá-lo no início da operação (0.0). Se o chamador não especificar isso, é opcional. Da mesma forma, se o chamador especificar WICProgerssNotificationEnd, você deverá chamá-lo quando a operação for concluída (1.0). Se o chamador especificar WICProgressNotificationAll, você deverá chamá-lo no início e no fim, bem como em intervalos regulares durante toda a operação. O chamador também pode especificar WICProgerssNotificationFrequent, o que indica que eles querem ser chamados de volta em intervalos frequentes, talvez após cada par de linhas de verificação. (Um chamador geralmente usará esse sinalizador apenas para uma imagem muito grande.) Caso contrário, você geralmente deve ligar de volta em intervalos de aproximadamente 10% incrementos do número total de linhas de verificação a serem processadas.

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

Apenas uma função callback pode ser registada de cada vez para uma instância específica de um descodificador ou codificador. Se uma aplicação chamar RegisterProgressNotification mais de uma vez, substitua a função de "callback" registrada anteriormente pela nova. Para cancelar um registo de retorno de chamada, o chamador definirá o parâmetro pfnProgressNotification como NULL.

PFNProgressNotification

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

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

Ao invocar a função de retorno de chamada, use o parâmetro pvData para passar de volta o mesmo pvData que o aplicativo especificou 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 operação como WICProgressOperationCopyPixels ao decodificar e WICProgressOperationWritePixels ao codificar.

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 varredura já processadas em relação ao número total de linhas de varredura a serem processadas.

Referência

NotificaçãoDeProgressoCallback

IWICBitmapCodecProgressNotification

Conceptual

Implementação do IWICBitmapDecoder

Implementar o IWICBitmapSource

Como escrever um WIC-Enabled CODEC

Visão geral do componente Windows Imaging