Implementación de IWICBitmapFrameEncode

  • Artículo

IWICBitmapFrameEncode

IWICBitmapFrameEncode es el homólogo del codificador de la interfaz IWICBitmapFrameDecode . Puede implementar esta interfaz en la clase de codificación de nivel de marco, que es la clase que realiza la codificación real de los bits de imagen para cada fotograma.

interface IWICBitmapFrameEncode : public IUnknown
{
   // Required methods
   HRESULT Initialize ( IPropertyBag2 *pIEncoderOptions );
   HRESULT SetSize ( UINT width,
               UINT height );
   HRESULT SetResolution ( double dpiX,
               double dpiY );
   HRESULT SetPixelFormat (WICPixelFormatGUID *pPixelFormat);
   HRESULT SetColorContexts ( UINT cCount,
               IWICColorContext **ppIColorContext );
   HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter 
               **ppIMetadataQueryWriter );
   HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
   HRESULT WritePixels ( UINT lineCount,
               UINT cbStride,
               UINT cbBufferSize,
               BYTE *pbPixels );
   HRESULT WriteSource ( IWICBitmapSource *pIWICBitmapSource,
               WICRect *prc );
   HRESULT Commit ( void );

// Optional method
   HRESULT SetPalette ( IWICPalette *pIPalette );
};

Initialize

Initialize es el primer método invocado en un objeto IWICBitmapFrameEncode después de crear una instancia. Este método tiene un parámetro , que se puede establecer en NULL. Este parámetro representa las opciones del codificador y es la misma instancia de IPropertyBag2 que creó en el método CreateNewFrame en el descodificador de nivel de contenedor y se pasa al autor de la llamada en el parámetro pIEncoderOptions de ese método. En ese momento, ha rellenado la estructura IPropertyBag2 con propiedades que representan las opciones de codificación admitidas por el codificador de nivel de fotograma. El autor de la llamada ahora ha proporcionado valores para esas propiedades para indicar determinados parámetros de opción de codificación y está pasando el mismo objeto de nuevo a usted para inicializar el objeto IWICBitmapFrameEncode . Debe aplicar las opciones especificadas al codificar los bits de imagen.

SetSize y SetResolution

SetSize y SetResolution son autoexplicativos. El llamador usa estos métodos para especificar el tamaño y la resolución de la imagen codificada.

SetPixelFormat

SetPixelFormat se usa para solicitar un formato de píxel en el que se codifica la imagen. Si no se admite el formato de píxel solicitado, debe devolver el GUID del formato de píxel más cercano que se admite en pPixelFormat, que es un parámetro de entrada y salida.

SetColorContexts

SetColorContexts se usa para especificar uno o varios contextos de color válidos (también conocidos como perfiles de color) para esta imagen. Es importante especificar los contextos de color, por lo que una aplicación que descodifica la imagen más adelante puede convertir del perfil de color de origen al perfil de destino del dispositivo que se usa para mostrar o imprimir la imagen. Sin un perfil de color, no es posible obtener colores coherentes en diferentes dispositivos. Esto puede ser frustrante para los usuarios finales cuando sus fotos se ven diferentes en diferentes monitores, y no pueden obtener las impresiones para que coincidan con lo que ven en la pantalla.

GetMetadataQueryWriter

GetMetadataQueryWriter devuelve un IWICMetadataQueryWriter que una aplicación puede usar para insertar o editar propiedades de metadatos específicas en un bloque de metadatos en el marco de imagen.

Puede crear una instancia de IWICMetadataQueryWriter desde IWICComponentFactory de varias maneras. Puede crearlo a partir de IWICMetadataBlockWriter, de la misma manera que se creó IWICMetadataQueryReader a partir de un IWICMetadataBlockReader en el método GetMetadataQueryReader en la interfaz IWICBitmapFrameDecode .

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

hr = m_piComponentFactory->CreateQueryWriterFromBlockWriter( 
      static_cast<IWICMetadataBlockWriter*>(this), 
      &piMetadataQueryWriter);

También puede crearlo a partir de un IWICMetadataQueryReader existente, como el obtenido mediante el método anterior.

hr = m_piComponentFactory->CreateQueryWriterFromReader( 
      piMetadataQueryReader, pguidVendor, &piMetadataQueryWriter);

El parámetro pguidVendor permite especificar un proveedor determinado para que el escritor de consultas lo use al crear instancias de un escritor de metadatos. Por ejemplo, si proporciona sus propios escritores de metadatos, puede especificar su propio GUID de proveedor. Puede pasar NULL a este parámetro si no tiene ninguna preferencia.

SetThumbnail

SetThumbnail se usa para proporcionar una miniatura. Todas las imágenes deben proporcionar una miniatura globalmente, en cada fotograma o ambos. Los métodos GetThumbnail y SetThumbnail son opcionales en el nivel de contenedor, pero, si un códec devuelve WINCODEC_ERR_CODECNOTHUMBNAIL del método GetThumbnail , Windows Imaging Component (WIC) invocará el método GetThumbnail para Frame 0. Si no se encuentra ninguna miniatura en ningún lugar, WIC debe descodificar la imagen completa y escalarla al tamaño de miniatura, lo que podría suponer una gran penalización de rendimiento para imágenes más grandes.

La miniatura debe tener un tamaño y una resolución que haga que sea rápido descodificar y mostrar. Por este motivo, las miniaturas son las imágenes JPEG más comunes. Tenga en cuenta que, si usa JPEG para las miniaturas, no tiene que escribir un codificador JPEG para codificarlos o un descodificador JPEG para descodificarlos. Siempre debe delegar en el códec JPEG que se incluye con la plataforma WIC para codificar y descodificar miniaturas.

WritePixels

WritePixels es el método que se usa para pasar líneas de examen desde un mapa de bits en memoria para la codificación. Se llamará repetidamente al método hasta que se hayan pasado todas las líneas de examen. El parámetro lineCount indica cuántas líneas de examen se van a escribir en esta llamada. El parámetro cbStride indica el número de bytes por línea de examen. cbBufferSize indica el tamaño del búfer pasado en el parámetro pbPixels, que contiene los bits de imagen reales que se van a codificar. Si el alto combinado de las líneas de examen de las llamadas acumulativas es mayor que el alto especificado en el método SetSize , devuelva WINCODEC_ERR_TOOMANYSCANLINES.

Cuando WICBitmapEncoderCacheOption es WICBitmapEncoderCacheInMemory, las líneas de examen deben almacenarse en memoria caché hasta que se hayan pasado todas las líneas de examen. Si la opción de caché del codificador es WICBitmapEncoderCacheTempFile, las líneas de examen deben almacenarse en caché en un archivo temporal, creado al inicializar el objeto. En cualquiera de estos casos, la imagen no se debe codificar hasta que el autor de la llamada llame a Commit. En el caso de que la opción de caché sea WICBitmapEncoderNoCache, el codificador debe codificar las líneas de examen a medida que se reciben, si es posible. (En algunos formatos, esto no es posible y las líneas de examen deben almacenarse en caché hasta que se llame a Commit).

La mayoría de los códecs sin formato no implementarán WritePixels, ya que no admiten la modificación de los bits de imagen en el archivo sin formato. Sin embargo, los códecs sin formato deben implementar WritePixels, ya que cuando se agregan metadatos, puede aumentar el tamaño del archivo, lo que requiere que el archivo se vuelva a escribir en el disco. En ese caso, es necesario poder copiar los bits de imagen existentes, que es lo que hace el método WritePixels .

WriteSource

WriteSource se usa para codificar un objeto IWICBitmapSource . El primer parámetro es un puntero a un objeto IWICBitmapSource . El segundo parámetro es un WICRect que especifica la región de interés que se va a codificar. Se puede llamar a este método varias veces sucesivamente, siempre que el ancho de cada rectángulo sea el mismo ancho de la imagen final que se va a codificar. Si el ancho del rectángulo pasado en el parámetro prc es diferente del ancho especificado en el método SetSize, devuelva WINCODEC_ERR_SOURCERECTDOESNOTMATCHDIMENSIONS. Si el alto combinado de las líneas de examen de las llamadas acumulativas es mayor que el alto especificado en el método SetSize, devuelva WINCODEC_ERR_TOOMANYSCANLINES.

Las opciones de caché funcionan de la misma manera con este método que con el método WritePixels descrito anteriormente.

Commit

Commit es el método que serializa los bits de imagen codificados en la secuencia de archivos y recorre en iteración todos los escritores de metadatos para el fotograma que los solicita para serializar sus metadatos en la secuencia. En el caso de que la opción de caché del codificador sea WICBitmapEncoderCacheInMemory o WICBitmapEncoderCacheTempFile, este método también es responsable de codificar la imagen y, cuando la opción de caché es WICBitmapEncoderCacheTempFile, el método Commit también debe eliminar el archivo temporal usado para almacenar en caché los datos de imagen antes de codificar.

Este método siempre se invoca después de que se hayan pasado todas las líneas de examen o rectángulos que componen la imagen mediante el método Commit o WriteSource . El tamaño del rectángulo final que se compone a través de las llamadas acumuladas a WritePixels o WriteSource debe tener el mismo tamaño que se especificó en el método SetSize. Si el tamaño no coincide con el tamaño esperado, este método debe devolver WINCODECERROR_UNEXPECTEDSIZE.

Para recorrer en iteración los escritores de metadatos e indicar a cada escritor de metadatos que serialice sus metadatos, invoque a GetWriterByIndex para recorrer en iteración los escritores de cada bloque e invoque IWICPersistStream.Save en cada escritor de metadatos.

IWICMetadataWriter* piMetadataWRiter = NULL;
IWICPersistStream* piPersistStream = NULL;
HRESULT hr;

for (UINT x=0; x < m_blockCount; x++) 
{
    hr = GetWriterByIndex(x, & piMetadataWriter);
hr = piMetadataWriter->QueryInterface(
IID_IWICPersistStream,(void**)&piPersistStream);

hr = piPersistStream->Save(m_piStream, 
WICPersistOptions.WicPersistOptionDefault, 
true);
...
}

SetPalette

Solo los códecs que tienen formatos indexados deben implementar el método SetPalette . Si una imagen usa un formato indizado, use este método para especificar la paleta de colores que se usa en la imagen. Si el códec no tiene un formato indizado, devuelva WINCODEC_ERR_PALETTEUNAVAILABLE de este método.

Conceptual

Implementación de IWICBitmapCodecProgressNotification (Codificador)

Implementación de IWICMetadataBlockWriter

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

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