Compartir a través de

Implementación de IWICBitmapDecoder

  • Artículo

IWICBitmapDecoder

Cuando una aplicación solicita un descodificador, el primer punto de interacción con el códec es a través de la interfaz IWICBitmapDecoder . Esta es la interfaz de nivel de contenedor que proporciona acceso a las propiedades de nivel superior del contenedor y, lo más importante, los marcos que contiene. Esta es la interfaz principal de la clase de descodificador de nivel de contenedor.

interface IWICBitmapDecoder : IUnknown
{
// Required methods
   HRESULT QueryCapability (IStream *pIStream, 
      DWORD *pdwCapabilities );
   HRESULT Initialize ( IStream *pIStream,
      WICDecodeOptions cacheOptions );
   HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
   HRESULT GetDecoderInfo ( IWICBitmapDecoderInfo **pIDecoderInfo );
   HRESULT GetFrameCount ( UINT *pCount );
   HRESULT GetFrame ( UINT index, 
      IWICBitmapFrameDecode **ppIBitmapFrame );

// Optional methods
   HRESULT GetPreview ( IWICBitmapSource **ppIPreview );
   HRESULT GetThumbnail ( IWICBitmapSource **ppIThumbnail );
   HRESULT GetColorContexts ( UINT cCount, 
      IWICColorContext **ppIColorContexts, 
      UINT *pcActualCount );
   HRESULT GetMetadataQueryReader ( IWICMetadataQueryReader **ppIMetadataQueryReader);
   HRESULT CopyPalette ( IWICPalette *pIPalette );
}

Algunos formatos de imagen tienen miniaturas globales, contextos de color o metadatos, mientras que muchos formatos de imagen solo los proporcionan por fotograma. Los métodos para acceder a estos elementos son opcionales en IWICBitmapDecoder, pero son necesarios en IWICBitmapFrameDecode. Del mismo modo, algunos códecs no usan formatos de píxeles indizado, por lo que no es necesario implementar los métodos CopyPalette en ninguna interfaz. Para obtener más información sobre los métodos opcionales de IWICBitmapDecoder , consulte Implementación de IWICBitmapFrameDecode, donde se implementan con más frecuencia.

QueryCapability

QueryCapability es el método que se usa para el arbitraje de códecs. (Consulte Detección y arbitraje en el tema Cómo funciona el componente de creación de imágenes de Windows ). Si dos códecs son capaces de descodificar el mismo formato de imagen, o si se produce una colisión de patrones en la que dos códecs usan el mismo patrón de identificación, este método permite seleccionar el códec que puede controlar mejor cualquier imagen específica.

Al invocar este método, Windows Imaging Component (WIC) pasa la secuencia real que contiene la imagen. Debe comprobar si puede descodificar cada fotograma dentro de la imagen y enumerar a través de los bloques de metadatos, para declarar con precisión qué funcionalidad tiene este descodificador con respecto a la secuencia de archivos específica que se le ha pasado. Esto es importante para todos los descodificadores, pero especialmente importante para los formatos de imagen basados en contenedores etiquetados de formato de archivo de imagen (TIFF). El proceso de detección funciona mediante la coincidencia de patrones asociados con descodificadores en el Registro con patrones en el archivo de imagen real. Declarar el patrón de identificación en el registro garantiza que el descodificador siempre se detectará para las imágenes en el formato de imagen. Sin embargo, el descodificador todavía se puede detectar para imágenes en otros formatos. Por ejemplo, todos los contenedores de TIFF incluyen el patrón TIFF, que es un patrón de identificación válido para el formato de imagen TIFF. Esto significa que, durante la detección, se encontrarán al menos dos patrones de identificación en archivos de imagen para cualquier formato de imagen basado en un contenedor de estilo TIFF. Uno será el patrón TIFF y el otro será el patrón de formato de imagen real. Aunque es menos probable, también podría haber colisiones de patrones entre otros formatos de imagen no relacionados. Este es el motivo por el que la detección y el arbitraje son un proceso de dos fases. Compruebe siempre que el flujo de imagen pasado a QueryCapability es realmente una instancia válida de su propio formato de imagen. Además, si el códec descodifica un formato de imagen para el que no es propietario de la especificación, la implementación queryCapability debe comprobar la presencia de cualquier característica que pueda ser válida en la especificación de formato de imagen que el códec no implementa. Esto garantizará que los usuarios no experimenten errores de descodificación innecesarios o obtengan resultados inesperados con el códec.

Antes de realizar cualquier operación en la imagen, debe guardar la posición actual de la secuencia, por lo que puede restaurarla en su posición original antes de volver desde el método . La enumeración WICBitmapDecoderCapabilities que especifica las funcionalidades se define de la siguiente manera:

enum WICBitmapDecoderCapabilities
{   
   WICBitmapDecoderCapabilitySameEncoder,
   WICBitmapDecoderCapabilityCanDecodeAllImages,
   WICBitmapDecoderCapabilityCanDecodeSomeImages,
   WICBitmapDecoderCapabilityCanEnumerateMetadata,
   WICBitmapDecoderCapabilityCanDecodeThumbnail
}

Debe declarar WICBitmapDecoderCapabilitySameEncoder solo si el codificador era el que codificó la imagen. Después de comprobar si puede descodificar cada fotograma del contenedor, declare WICBitmapDecoderCapabilityCanDecodeSomeImages si puede descodificar algunos pero no todos los fotogramas, WICBitmapDecoderCapabilityCanDecodeAllImages si puede descodificar todos los fotogramas, o tampoco si no puede descodificar ninguno de ellos. (Estas dos enumeraciones son mutuamente excluyentes; si devuelve WICBitmapDecoderCapabilityCanDecodeAllImages, WICBitmapDecoderCapabilityCanDecodeSomeImages se omitirán). Declare WICBitmapDecoderCapabilityCanEnumerateMetadata después de comprobar que puede enumerar los bloques de metadatos del contenedor de imágenes. No es necesario comprobar si hay una miniatura en cada fotograma. Si hay una miniatura global y puede descodificarla, puede declarar WICBitmapDecoderCapabilityCanDecodeThumbnail. Si no hay ninguna miniatura global, intente descodificar la miniatura para Frame 0. Si no hay ninguna miniatura en ninguno de estos lugares, no declare esta funcionalidad.

Después de determinar las funcionalidades del descodificador con respecto al flujo de imagen pasado a este método, realice una operación OR con WICBitmapDecoderCapabilities que haya comprobado que este descodificador puede realizar en esta imagen y devolver el resultado. Recuerde restaurar la secuencia en su posición original antes de devolverla.

Initialize

Una aplicación invoca initialize después de que se haya seleccionado un descodificador para descodificar una imagen específica. La secuencia de imágenes se pasa al descodificador y, opcionalmente, un autor de la llamada puede especificar la opción de caché WICDecodeOptions para tratar con los metadatos del archivo.

enum WICDecodeOptions
{
   WICDecodeMetadataCacheOnDemand,
   WICDecodeMetadataCacheOnLoad
}

Algunas aplicaciones usan metadatos más que otros. La mayoría de las aplicaciones no necesitan acceder a todos los metadatos de un archivo de imagen y solicitarán metadatos específicos según lo necesiten. Otras aplicaciones prefieren almacenar en caché todos los metadatos por adelantado que mantener abierta la secuencia de archivos y realizar E/S de disco cada vez que necesiten acceder a los metadatos. Si el autor de la llamada no especifica una opción de caché de metadatos, el comportamiento de almacenamiento en caché predeterminado debe ser caché a petición. Esto significa que no se debe cargar ningún metadato en la memoria hasta que la aplicación realice una solicitud específica para esos metadatos. Si la aplicación especifica WICDecodeMetadataCacheOnLoad, los metadatos deben cargarse en memoria inmediatamente y almacenarse en caché. Cuando los metadatos se almacenan en caché durante la carga, la secuencia de archivos se puede liberar una vez almacenados en caché los metadatos.

GetContainerFormat

Para implementar GetContainerFormat, solo tiene que devolver el GUID del formato de imagen de la imagen para la que se crea una instancia del descodificador. Este método también se implementa en IWICMetadataBlockReader e IWICBitmapEncoder.

GetDecoderInfo

GetDecoderInfo devuelve un objeto IWICBitmapDecoderInfo . Para obtener el objeto IWICBitmapDecoderInfo , simplemente pase el GUID del descodificador al método CreateComponentInfo en IWICImagingFactory y, a continuación, solicite la interfaz IWICBitmapDecoderInfo en él, como se muestra en el ejemplo siguiente.

IWICComponentInfo* pComponentInfo = NULL;
HRESULT hr;
 
hr = m_pImagingFactory->CreateComponentInfo(CLSID_This, &pComponentInfo);

hr = pComponentInfo->QueryInterface(IID_IWICBitmapDecoderInfo, (void**)ppIDecoderInfo);

GetFrameCount

GetFrameCount solo devuelve el número de fotogramas del contenedor. Algunos formatos de contenedor admiten varios fotogramas y otros solo admiten un fotograma por contenedor.

GetFrame

GetFrame es un método importante en la interfaz IWICBitmapDecoder porque el fotograma contiene los bits de imagen reales y el objeto de descodificador de fotogramas devuelto desde este método es el objeto que realiza la descodificación real de la imagen solicitada. Ese es el otro objeto que debe implementar al escribir un descodificador. Para obtener más información sobre los descodificadores de fotogramas, consulte Implementación de IWICBitmapFrameDecode.

GetPreview

GetPreview devuelve una vista previa de la imagen. Para obtener una explicación detallada de las versiones preliminares, consulte el método Implementing IWICBitmapEncoder en la interfaz Implementing IWICBitmapEncoder .

Si el formato de imagen contiene una vista previa JPEG incrustada, se recomienda encarecidamente que, en lugar de escribir un descodificador JPEG para descodificarlo, delega en el descodificador JPEG que se incluye con la plataforma WIC para descodificar vistas previas y miniaturas. Para ello, busque el principio de los datos de la imagen de vista previa en la secuencia e invoque el método CreateDecoderFromStream en IWICImagingFactory.

IWICBitmapDecoder* pPreviewDecoder = NULL;
IWICBitmapFrameDecode* pPreviewFrame = NULL;
IWICBitmapSource* pPreview = NULL;
HRESULT hr;

hr = m_pImagingFactory->CreateDecoderFromStream(
                               m_pStream, NULL, 
                               WICDecodeMetadataCacheOnDemand, &pPreviewDecoder);
hr = pPreviewDecoder->GetFrame(0, pPreviewFrame);
hr = pPreviewFrame->QueryInterface(IID_IWICBitmapSource, (void**)&pPreview);

Referencia

IWICBitmapDecoder

IWICBitmapFrameDecode

Conceptual

Interfaces de descodificador

Implementación de IWICBitmapCodecProgressNotification (Decoder)

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

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