Condividi tramite

Implementazione di IWICBitmapCodecProgressNotification (decodificatore)

  • Articolo

IWICBitmapCodecProgressNotification

Quando un codec esegue un'operazione di I/O, ad esempio CopyPixels in un'immagine di grandi dimensioni, il completamento può richiedere alcuni secondi o anche minuti. Quando gli utenti finali non sono in grado di interrompere un'operazione a esecuzione prolungata, potrebbero pensare che l'applicazione sia bloccata. Gli utenti spesso chiudono un'applicazione o riavviano i computer, nel tentativo di riprendere il controllo del computer quando un'applicazione non risponde.

Questa interfaccia consente a un'applicazione di specificare una funzione di callback che il codec può chiamare a intervalli specificati per notificare al chiamante lo stato di avanzamento dell'operazione corrente. L'applicazione può usare questa funzione di callback per visualizzare un'indicazione dello stato di avanzamento nell'interfaccia utente per notificare all'utente lo stato dell'operazione. Se un utente fa clic sul pulsante Annulla nella finestra di dialogo Stato , l'applicazione restituisce WINCODEC_ERR_ABORTED dalla funzione di callback. In questo caso, il codec deve annullare l'operazione specificata e propagare il valore HRESULT al chiamante del metodo che esegue l'operazione.

Questa interfaccia deve essere implementata nella classe decodificatore a livello di contenitore.

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

RegisterProgressNotification

RegisterProgressNotification viene richiamato da un'applicazione per registrare una funzione di callback che il codec può chiamare a intervalli specificati. Il primo parametro , pfnProgressNotification, è un puntatore alla funzione di callback che il codec deve chiamare a intervalli regolari.

Il parametro pvData punta a un oggetto che il chiamante desidera che il codec passi alla funzione di callback ogni volta che viene richiamata la funzione di callback. Questo oggetto può essere qualsiasi elemento e non ha alcun significato particolare per il codec.

Il parametro dwProgressFlags specifica quando il codec deve chiamare la funzione di callback. È possibile eseguire una funzione OR con due enumerazioni per questo parametro. L'enumerazione WICProgressOperation specifica se chiamare la funzione di callback durante la decodifica (WICProgressOperationCopyPixels), la codifica (WICProgerssOperationWritePixels) o entrambe (WICProgressOperationAll).

enum WICProgressOperation
{
   WICProgressOperationCopyPixels,
   WICProgerssOperationWritePixels,
   WICProgressOperationAll      
};

Il codec deve chiamare la funzione di callback a intervalli regolari durante l'operazione, ma il chiamante può specificare determinati requisiti. L'enumerazione WICProgressNotification indica a quale punto dell'operazione chiamare la funzione di callback. Se il chiamante specifica WICProgressNotificationBegin, è necessario chiamarlo all'inizio dell'operazione (0,0). Se il chiamante non specifica questo valore, è facoltativo. Analogamente, se il chiamante specifica WICProgerssNotificationEnd, è necessario chiamarlo al termine dell'operazione (1.0). Se il chiamante specifica WICProgressNotificationAll, è necessario chiamarlo all'inizio e alla fine, nonché a intervalli regolari durante l'operazione. Il chiamante può anche specificare WICProgerssNotificationFrequent, che indica che vogliono essere richiamati a intervalli frequenti, ad esempio dopo ogni coppia di righe di analisi. Un chiamante usa in genere questo flag solo per un'immagine molto grande. In caso contrario, è in genere consigliabile richiamare a intervalli di circa il 10% incrementi del numero totale di righe di analisi da elaborare.

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

È possibile registrare una sola funzione di callback alla volta per un decodificatore o un'istanza del codificatore specifica. Se un'applicazione chiama RegisterProgressNotification più volte, sostituire la funzione di callback registrata in precedenza con quella nuova. Per annullare una registrazione di callback, un chiamante imposterà il parametro pfnProgressNotification su NULL.

PFNProgressNotification

PFNProgressNotification è la funzione di callback con la firma seguente.

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

Quando si richiama la funzione di callback, usare il parametro pvData per passare lo stesso pvData specificato dall'applicazione quando ha registrato la funzione di callback.

Il parametro uFrameNum deve indicare l'indice del frame in fase di elaborazione.

Impostare il parametro operation su WICProgressOperationCopyPixels durante la decodifica e WICProgressOperationWritePixels durante la codifica.

Il parametro dblProgress deve essere un numero compreso tra 0,0 (l'inizio dell'operazione) e 1,0 (completamento dell'operazione). Il valore deve riflettere la proporzione di righe di analisi già elaborate rispetto al numero totale di righe di analisi da elaborare.

Riferimento

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

Informazioni concettuali

Implementazione di IWICBitmapDecoder

Implementazione di IWICBitmapSource

Come scrivere un codec WIC-Enabled

Panoramica del componente Windows Imaging