Implementación de IWICBitmapCodecProgressNotification (Decoder)

  • Artículo

IWICBitmapCodecProgressNotification

Cuando un códec realiza una operación de E/S como CopyPixels en una imagen grande, puede tardar varios segundos o incluso minutos en completarse. Cuando los usuarios finales no pueden interrumpir una operación de larga duración, pueden pensar que la aplicación se ha bloqueado. A menudo, los usuarios cerrarán una aplicación, o incluso reiniciarán sus equipos, en un intento de recuperar el control de su equipo cuando una aplicación deje de responder.

Esta interfaz permite a una aplicación especificar una función de devolución de llamada a la que el códec puede llamar a intervalos especificados para notificar al autor de la llamada el progreso de la operación actual. La aplicación puede usar esta función de devolución de llamada para mostrar una indicación del progreso en la interfaz de usuario para notificar al usuario el estado de la operación. Si un usuario hace clic en el botón Cancelar del cuadro de diálogo Progreso , la aplicación devuelve WINCODEC_ERR_ABORTED de la función de devolución de llamada. Cuando esto sucede, el códec debe cancelar la operación especificada y volver a propagar este HRESULT al autor de la llamada del método que estaba realizando la operación.

Esta interfaz debe implementarse en la clase de descodificador de nivel de contenedor.

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

RegisterProgressNotification

RegisterProgressNotification lo invoca una aplicación para registrar una función de devolución de llamada a la que el códec puede llamar a intervalos especificados. El primer parámetro, pfnProgressNotification, es un puntero a la función de devolución de llamada a la que el códec debe llamar a intervalos regulares.

El parámetro pvData apunta a algún objeto que el autor de la llamada quiere que el códec vuelva a la función de devolución de llamada siempre que se invoque la función de devolución de llamada. Este objeto puede ser cualquier cosa y no tiene ninguna importancia particular para el códec.

El parámetro dwProgressFlags especifica cuándo el códec debe llamar a la función de devolución de llamada. Se puede realizar una función OR con dos enumeraciones para este parámetro. La enumeración WICProgressOperation especifica si se debe llamar a la función de devolución de llamada durante la descodificación (WICProgressOperationCopyPixels), la codificación (WICProgerssOperationWritePixels) o ambas (WICProgressOperationAll).

enum WICProgressOperation
{
   WICProgressOperationCopyPixels,
   WICProgerssOperationWritePixels,
   WICProgressOperationAll      
};

El códec debe llamar a la función de devolución de llamada a intervalos regulares a lo largo de la operación, pero el autor de la llamada puede especificar determinados requisitos. La enumeración WICProgressNotification indica en qué punto de la operación se llama a la función de devolución de llamada. Si el autor de la llamada especifica WICProgressNotificationBegin, debe llamarlo al principio de la operación (0.0). Si el autor de la llamada no lo especifica, es opcional. Del mismo modo, si el autor de la llamada especifica WICProgerssNotificationEnd, debe llamarlo cuando se complete la operación (1.0). Si el autor de la llamada especifica WICProgressNotificationAll, debe llamarlo al principio y al final, así como a intervalos regulares a lo largo de la operación. El autor de la llamada también puede especificar WICProgerssNotificationFrequent, lo que indica que quieren llamarse a intervalos frecuentes, quizás después de cada par de líneas de examen. (Normalmente, un autor de llamada usará esta marca solo para una imagen muy grande). De lo contrario, normalmente debe volver a llamar a intervalos de aproximadamente un 10 % de incrementos del número total de líneas de examen que se van a procesar.

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

Solo se puede registrar una función de devolución de llamada a la vez para una instancia específica de descodificador o codificador. Si una aplicación llama a RegisterProgressNotification más de una vez, reemplace la función de devolución de llamada registrada anteriormente por la nueva. Para cancelar un registro de devolución de llamada, un llamador establecerá el parámetro pfnProgressNotification en NULL.

PFNProgressNotification

PFNProgressNotification es la función de devolución de llamada con la siguiente firma.

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

Al invocar la función de devolución de llamada, use el parámetro pvData para devolver el mismo pvData que la aplicación especificó cuando registró la función de devolución de llamada.

El parámetro uFrameNum debe indicar el índice del marco que se está procesando.

Establezca el parámetro operation en WICProgressOperationCopyPixels al descodificar y WICProgressOperationWritePixels al codificar.

El parámetro dblProgress debe ser un número comprendido entre 0,0 (el principio de la operación) y 1,0 (la finalización de la operación). El valor debe reflejar la proporción de líneas de examen ya procesadas en relación con el número total de líneas de examen que se van a procesar.

Referencia

ProgressNotificationCallback

IWICBitmapCodecProgressNotification

Conceptual

Implementación de IWICBitmapDecoder

Implementación de IWICBitmapSource

Cómo escribir un CÓDEC de WIC-Enabled

Información general sobre el componente de creación de imágenes de Windows