Share via

Implementieren von IWICBitmapCodecProgressNotification (Decoder)

  • Artikel

IWICBitmapCodecProgressNotification

Wenn ein Codec einen E/A-Vorgang wie CopyPixels für ein großes Bild ausführt, kann es einige Sekunden oder sogar Minuten dauern, bis er abgeschlossen ist. Wenn Endbenutzer einen lang andauernden Vorgang nicht unterbrechen können, denken sie möglicherweise, dass die Anwendung hängen geblieben ist. Benutzer schließen häufig eine Anwendung oder starten sogar ihre Computer neu, um die Kontrolle über ihren Computer wiederzuerlangen, wenn eine Anwendung nicht mehr reagiert.

Mit dieser Schnittstelle kann eine Anwendung eine Rückruffunktion angeben, die der Codec in bestimmten Intervallen aufrufen kann, um den Aufrufer über den Fortschritt des aktuellen Vorgangs zu benachrichtigen. Die Anwendung kann diese Rückruffunktion verwenden, um einen Fortschrittshinweis auf der Benutzeroberfläche anzuzeigen, um den Benutzer über die status des Vorgangs zu benachrichtigen. Wenn ein Benutzer im Dialogfeld Status auf die Schaltfläche Abbrechen klickt, gibt die Anwendung WINCODEC_ERR_ABORTED aus der Rückruffunktion zurück. In diesem Fall muss der Codec den angegebenen Vorgang abbrechen und dieses HRESULT zurück an den Aufrufer der Methode weitergeben, die den Vorgang ausgeführt hat.

Diese Schnittstelle sollte für Ihre Decoderklasse auf Containerebene implementiert werden.

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

RegisterProgressNotification

RegisterProgressNotification wird von einer Anwendung aufgerufen, um eine Rückruffunktion zu registrieren, die der Codec in bestimmten Intervallen aufrufen kann. Der erste Parameter, pfnProgressNotification, ist ein Zeiger auf die Rückruffunktion, die der Codec in regelmäßigen Abständen aufrufen soll.

Der pvData-Parameter verweist auf ein Objekt, das der Aufrufer möchte, dass der Codec an die Rückruffunktion zurückgegeben werden soll, wenn die Rückruffunktion aufgerufen wird. Dieses Objekt kann überhaupt etwas sein und hat keine besondere Bedeutung für den Codec.

Der dwProgressFlags-Parameter gibt an, wann der Codec die Rückruffunktion aufrufen soll. Eine OR-Funktion kann mit zwei Enumerationen für diesen Parameter ausgeführt werden. Die WICProgressOperation-Enumeration gibt an, ob die Rückruffunktion während der Decodierung (WICProgressOperationCopyPixels), der Codierung (WICProgerssOperationWritePixels) oder beides (WICProgressOperationAll) aufgerufen werden soll.

enum WICProgressOperation
{
   WICProgressOperationCopyPixels,
   WICProgerssOperationWritePixels,
   WICProgressOperationAll      
};

Der Codec sollte die Rückruffunktion während des gesamten Vorgangs in regelmäßigen Abständen aufrufen, aber der Aufrufer kann bestimmte Anforderungen angeben. Die WICProgressNotification-Enumeration gibt an, an welcher Stelle im Vorgang die Rückruffunktion aufgerufen werden soll. Wenn der Aufrufer WICProgressNotificationBegin angibt, müssen Sie ihn zu Beginn des Vorgangs (0.0) aufrufen. Wenn der Aufrufer dies nicht angibt, ist dies optional. Wenn der Aufrufer WICProgerssNotificationEnd angibt, müssen Sie ihn aufrufen, wenn der Vorgang abgeschlossen ist (1.0). Wenn der Aufrufer WICProgressNotificationAll angibt, müssen Sie ihn am Anfang und Ende sowie in regelmäßigen Abständen während des Vorgangs aufrufen. Der Aufrufer kann auch WICProgerssNotificationFrequent angeben, was angibt, dass er in regelmäßigen Abständen, vielleicht nach jeder Paar Scanzeile, zurückrufen möchte. (Ein Aufrufer verwendet dieses Flag normalerweise nur für ein sehr großes Bild.) Andernfalls sollten Sie in der Regel in Abständen von etwa 10 Prozent der Gesamtzahl der zu verarbeitenden Scanzeilen zurückrufen.

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

Für einen bestimmten Decoder oder Encoder kann jeweils nur eine Rückruffunktion registriert werden instance. Wenn eine Anwendung RegisterProgressNotification mehrmals aufruft , ersetzen Sie die zuvor registrierte Rückruffunktion durch die neue Funktion. Um eine Rückrufregistrierung abzubrechen, legt ein Aufrufer den PfnProgressNotification-Parameter auf NULL fest.

PFNProgressNotification

PFNProgressNotification ist die Rückruffunktion mit der folgenden Signatur.

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

Wenn Sie die Rückruffunktion aufrufen, verwenden Sie den pvData-Parameter , um denselben pvData-Wert zurück zu übergeben, den die Anwendung beim Registrieren der Rückruffunktion angegeben hat.

Der uFrameNum-Parameter sollte den Index des zu verarbeitenden Frames angeben.

Legen Sie den Vorgangsparameter beim Decodieren auf WICProgressOperationCopyPixels und bei der Codierung AUF WICProgressOperationWritePixels fest.

Der dblProgress-Parameter sollte eine Zahl zwischen 0,0 (Beginn des Vorgangs) und 1.0 (Abschluss des Vorgangs) sein. Der Wert sollte den Anteil der bereits verarbeiteten Scanlinien im Verhältnis zur Gesamtanzahl der zu verarbeitenden Scanzeilen widerspiegeln.

Referenz

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

Konzept

Implementieren von IWICBitmapDecoder

Implementieren von IWICBitmapSource

Schreiben eines WIC-Enabled CODEC

Übersicht über die Windows-Bildverarbeitungskomponente