Implementación de IWICBitmapEncoder

  • Artículo

IWICBitmapEncoder

Esta interfaz es el homólogo de la interfaz IWICBitmapDecoder y es el punto de partida para codificar un archivo de imagen. Al igual que IWICBitmapDecoder se usa para recuperar propiedades de nivel de contenedor y marcos individuales del contenedor de imágenes, IWICBitmapEncoder se usa para establecer propiedades de nivel de contenedor y serializar fotogramas de imagen individuales en el contenedor. Esta interfaz se implementa en la clase de codificador de nivel de contenedor.

interface IWICBitmapEncoder : public IUnknown
{
   // Required methods
   HRESULT Initialize ( IStream *pIStream,
              WICBitmapEncoderCacheOption cacheOption );
   HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
   HRESULT GetEncoderInfo ( IWICBitmapEncoderInfo **pIEncoderInfo );
   HRESULT CreateNewFrame ( IWICBitmapFrameEncode **ppIFrameEncode,
              IPropertyBag2 **ppIEncoderOptions );
   HRESULT Commit ( void );

   // Optional methods
   HRESULT SetPreview ( IWICBitmapSource *pIPreview );
   HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
   HRESULT SetColorContexts ( UINT cCount,
              IWICColorContext **ppIColorContext );
   HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter 
              **ppIMetadataQueryWriter );
   HRESULT SetPalette ( IWICPalette *pIPalette);
};

Como se describe en Implementación de IWICBitmapDecoder, algunos formatos de imagen tienen miniaturas globales, contextos de color o metadatos, mientras que muchos formatos de imagen solo proporcionan estos formatos por fotograma. Por lo tanto, los métodos para establecerlos son opcionales en IWICBitmapEncoder, pero son necesarios en IWICBitmapFrameEncode. Analizaremos los métodos que son opcionales en IWICBitmapEncoder en la sección de IWICBitmapFrameEncode, donde se implementan con más frecuencia.

Si no admite miniaturas globales, devuelva WINCODEC_ERR_CODECNOTHUMBNAIL del método SetThumbnail en IWICBitmapEncoder. Si no admite una paleta de nivel de contenedor o si la imagen que está codificando no tiene un formato indizado, devuelva WINCODEC_ERR_PALETTEUNAVAILABLE desde el método SetPalette. Para cualquier otro método no admitido, devuelva WINCODEC_ERR_UNSUPPORTEDOPERATION.

Initialize

Initialize es el primer método invocado en un IWICBitmapEncoder una vez creado una instancia. Un flujo de imagen se pasa al codificador y un autor de la llamada puede especificar opcionalmente una opción de caché. En el caso del descodificador, la secuencia es de solo lectura, pero la secuencia pasada a un codificador es una secuencia que se puede escribir, en la que el codificador serializará todos los datos y metadatos de la imagen. Las opciones de caché del codificador también son diferentes.

enum WICBitmapEncoderCacheOption
{
   WICBitmapEncoderCacheInMemory,
   WICBitmapEncoderCacheTempFile,
   WICBitmapEncoderNoCache
}

La aplicación tiene la opción de solicitar al codificador que almacene en caché los datos de imagen en memoria, almacenarlos en caché en un archivo temporal o escribirlos directamente en el archivo de disco sin almacenamiento en caché. Cuando se le pide que almacene en caché los datos en un archivo temporal, el codificador debe crear un archivo temporal en el disco y escribir directamente en ese archivo sin almacenar en caché en memoria. Cuando el autor de la llamada selecciona la opción sin caché, cada fotograma debe confirmarse para poder crear el siguiente fotograma.

GetContainerFormat

GetContainerFormat se implementa de la misma manera que el método GetContainerFormat en Implementación de IWICBitmapDecoder.

GetEncoderInfo

GetEncoderInfo devuelve un objeto IWICBitmapEncoderInfo . Para obtener el objeto IWICBitmapEncoderInfo , basta con pasar el GUID del codificador al método CreateComponentInfo en IWICImagingFactory y, a continuación, solicitar la interfaz IWICBitmapEncoderInfo en él.

Consulte el ejemplo de Implementación de IWICBitmapDecoder en GetDecoderInfo.

CreateNewFrame

CreateNewFrame es el homólogo codificador de GetFrame en IWICBitmapDecoder. Este método devuelve un objeto IWICBitmapFrameEncode , que es el objeto que serializa realmente los datos de imagen para un marco específico dentro del contenedor.

Una de las ventajas de Windows Imaging Component (WIC) es que proporciona una capa de abstracción para las aplicaciones que les permite trabajar con todos los formatos de imagen de la misma manera. Sin embargo, no todos los formatos de imagen son exactamente los mismos. Algunos formatos de imagen tienen funcionalidades que otras no tienen. Para que las aplicaciones puedan aprovechar esas funcionalidades únicas, es necesario proporcionar una manera de que el códec los exponga. Este es el propósito de las opciones del codificador. Si el códec admite cualquier opción de codificador, debe crear un objeto IPropertyBag2 que exponga las opciones de codificador que admita y devolverlo en el parámetro ppIEncoderOptions de este método. A continuación, el autor de la llamada puede usar este objeto IPropertyBag2 para determinar qué opciones de codificador admite el códec. Si el autor de la llamada quiere especificar valores para cualquiera de las opciones de codificador admitidas, asignará el valor a la propiedad pertinente en el objeto IPropertyBag2 y lo pasará al objeto IWICBitmapFrameEncode recién creado en su método Initialize.

Para crear una instancia de un objeto IPropertyBag2 , primero debe crear una estructura PROPBAG2 para especificar cada opción de codificador que admita el codificador y su tipo de datos para cada propiedad. A continuación, debe implementar un objeto IPropertyBag2 que aplique los intervalos de valores para cada propiedad en escritura y concilie los valores en conflicto o superpuestos. Para conjuntos sencillos de opciones de codificador no conflictivas, puede invocar el método CreateEncoderPropertyBag , que creará un objeto IPropertyBag2 simple con las propiedades que especifique en la estructura PROPBAG2. Todavía debe aplicar los intervalos de valores. Para obtener opciones de codificador más avanzadas o si necesita conciliar valores en conflicto, debe escribir su propia implementación de IPropertyBag2.

UINT cuiPropertyCount = 0;
IPropertyBag2* pPropertyBag = NULL;
PROPBAG2* pPropBagOptions;
HRESULT hr;

// Insert code here to initialize piPropertyBag with the 
// supported options for your encoder, and to initialize 
// cuiPropertyCount to the number of encoder option properties
// you are exposing.
...

hr = pComponentFactory->CreateEncoderPropertyBag( 
   pPropBagOptions, cuiPropertyCount, &pPropertyBag);

WIC proporciona un pequeño conjunto de opciones de codificador canónico que usan algunos de los formatos de imagen comunes. Todas las opciones del codificador canónico son opcionales y los códecs no son necesarios para admitir ninguno de ellos. La razón por la que se proporcionan como opciones canónicas es que muchas aplicaciones exponen la interfaz de usuario para que los usuarios especifiquen estas opciones al guardar un archivo de imagen en un formato que los admita. Proporcionar una manera canónica de especificar estas opciones facilita a las aplicaciones comunicarlas a codificadores de forma coherente. Las opciones del codificador canónico se muestran en la tabla siguiente.

Opción de codificador VARTYPE Intervalo de valores
Lossless VT_BOOL Verdadero/Falso
ImageQuality VT_R4 0.0-1.0
CompressionQuality VT_R4 0.0-1.0
BitmapTransform VT_UI1 WICBitmapTransformOptions

 

Si el códec admite la codificación sin pérdida, debe exponer la opción Codificador sin pérdida como una manera de que las aplicaciones soliciten que una imagen se codifique sin pérdida. Si un llamador establece esta propiedad en True, debe omitir la opción ImageQuality y codificar la imagen sin pérdida.

La opción ImageQuality permite a una aplicación especificar el grado de fidelidad con el que codificar la imagen. Esta opción permite a un usuario compensar la calidad de la imagen frente a la velocidad o el tamaño del archivo. JPEG es un ejemplo de un formato de imagen que admite este equilibrio. Un valor de 0,0 indica que la fidelidad es de baja importancia y el codificador debe usar su algoritmo más perdido. Un valor de 1.0 indica que la fidelidad es la más importante y el codificador debe conservar la mayor fidelidad posible. (Dependiendo del códec, esto puede ser sinónimo de la opción Lossless. Sin embargo, si el códec admite la codificación sin pérdida y si la opción Lossless está establecida en True, se debe omitir la opción ImageQuality).

La opción CompressionQuality permite a una aplicación especificar la eficacia de la compresión que se va a usar al codificar la imagen. Un algoritmo muy eficaz puede producir un archivo de imagen más pequeño con la misma calidad que un algoritmo de compresión menos eficaz, pero puede tardar más tiempo en codificar. Esta opción permite a un usuario especificar un equilibrio entre el tamaño de archivo y la velocidad de codificación, a la vez que se conserva el mismo nivel de calidad. TIFF es un ejemplo de un formato de imagen que admite este equilibrio. (Tenga en cuenta que un formato como JPEG admite distintos niveles de compresión, pero una mayor tasa de compresión da como resultado una menor calidad de imagen. Por lo tanto, un formato de imagen JPEG expondría la opción ImageQuality en lugar de la opción CompressionQuality). Un valor de 0,0 para esta opción indica que debe comprimir la imagen lo antes posible, sin reducir la fidelidad, a costa de un tamaño de archivo mayor. Un valor de 1.0 indica que debe crear el tamaño de archivo más pequeño posible (en el mismo nivel de calidad), independientemente del tiempo que tarde en codificarlo. Un códec puede admitir la opción ImageQuality y la opción CompressionQuality, donde la opción ImageQuality especifica el grado aceptable de pérdida y la opción CompressionQuality ofrece un equilibrio de tamaño y velocidad en el nivel de calidad especificado.

La opción BitmapTransform proporciona una manera de que el autor de la llamada especifique un ángulo de rotación o orientación de volteo vertical u horizontal al codificar. La enumeración WICBitmapTransformOptions usada para especificar la transformación solicitada es la misma enumeración que se usa al solicitar una transformación durante la descodificación a través de la interfaz IWICBitmapSourceTransform.

Tenga en cuenta que los codificadores no se limitan a las opciones del codificador canónico. El propósito de las opciones del codificador es permitir que los codificadores expongan sus funcionalidades y no hay ningún límite para los tipos de funcionalidades que puede exponer. Asegúrese de que las opciones del codificador estén bien documentadas. Aunque una aplicación puede usar el contenedor de propiedades que se devuelve desde este método para detectar los nombres, los tipos y los intervalos de valores para las opciones que admite, la única manera de averiguar sus significados o cómo exponerlos en la interfaz de usuario, procede de la documentación.

Commit

Commit es el método al que se llama después de que todos los datos y metadatos de la imagen se hayan serializado en la secuencia. Debe usar este método para serializar los datos de la imagen de vista previa en la secuencia y cualquier miniatura global, metadatos, paleta u otros elementos, si procede. Este método no debe cerrar la secuencia de archivos, ya que se espera que la aplicación que abrió la secuencia lo cierre.

La sección del método IWICBitmapFrameEncode:Commit tiene detalles sobre cómo IWICBitmapEncoderCacheOptions afecta al comportamiento de este método.

SetPreview

SetPreview se usa para crear una vista previa de la imagen. Aunque no es estrictamente necesario que todas las imágenes tengan una vista previa, se recomienda encarecidamente. Las cámaras digitales y escáneres modernos generan imágenes de muy alta resolución, que tienden a ser muy grandes y, por consiguiente, tardan mucho tiempo de procesamiento en descodificarse. Las imágenes de la próxima generación de cámaras serán aún más grandes. Es recomendable proporcionar una versión de resolución más pequeña y baja de una imagen, normalmente en formato JPEG, que se puede descodificar y mostrar rápidamente "al instante" cuando un usuario lo solicita. Una aplicación puede solicitar una vista previa antes de solicitar la descodificación de la imagen real para proporcionar una mejor experiencia para los usuarios y mostrarles una representación de tamaño de pantalla de la imagen mientras esperan descodificar la imagen real. Aunque los códecs deben proporcionar vistas previas, los códecs que no admiten IWICBitmapSourceTransform deben hacerlo definitivamente.

Si proporciona una vista previa JPEG, no tiene que escribir un codificador JPEG para codificarlo. Debe delegar en el codificador JPEG que se incluye con la plataforma WIC para codificar las vistas previas y las miniaturas.

Referencia

IWICBitmapEncoder

IWICBitmapFrameEncode

Conceptual

Interfaces de codificador

Implementación de IWICBitmapCodecProgressNotification (Codificador)

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

Información general del componente de creación de imágenes de Windows