Partilhar via

Implementando IWICBitmapEncoder

  • Artigo

IWICBitmapEncoder

Esta interface é a contrapartida da interfaceIWICBitmapDecoder e é o ponto de partida para codificar um arquivo de imagem. Assim como IWICBitmapDecoder é usado para recuperar propriedades no nível do contêiner e quadros individuais do contêiner de imagem, IWICBitmapEncoder é usado para definir propriedades no nível do contêiner e serializar quadros de imagem individuais no contêiner. Você implementa essa interface em sua classe de codificador de nível de contêiner.

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);
};

Conforme discutido em Implementing IWICBitmapDecoder, alguns formatos de imagem têm miniaturas globais, contextos de cores ou metadados, enquanto muitos formatos de imagem fornecem esses dados apenas por quadro. Portanto, os métodos para defini-los são opcionais em IWICBitmapEncoder, mas são necessários em IWICBitmapFrameEncode. Vamos discutir os métodos que são opcionais em IWICBitmapEncoder na seção sobre IWICBitmapFrameEncode, onde são mais comumente implementados.

Se não suportar miniaturas globais, devolva WINCODEC_ERR_CODECNOTHUMBNAIL do método SetThumbnail em IWICBitmapEncoder. Se você não oferecer suporte a uma paleta de nível de contêiner ou se a imagem que você está codificando não tiver um formato indexado, retorne WINCODEC_ERR_PALETTEUNAVAILABLE do método SetPalette. Para quaisquer outros métodos sem suporte, retorne WINCODEC_ERR_UNSUPPORTEDOPERATION.

Inicializar

Initialize é o primeiro método invocado em um IWICBitmapEncoder depois de ter sido instanciado. Um fluxo de imagem é passado para o codificador e um chamador pode, opcionalmente, especificar uma opção de cache. No caso do decodificador, o fluxo é somente leitura, mas o fluxo passado para um codificador é um fluxo gravável, no qual o codificador serializará todos os dados e metadados da imagem. As opções de cache no codificador também são diferentes.

enum WICBitmapEncoderCacheOption
{
   WICBitmapEncoderCacheInMemory,
   WICBitmapEncoderCacheTempFile,
   WICBitmapEncoderNoCache
}

O aplicativo tem a opção de solicitar ao codificador para armazenar em cache os dados da imagem na memória, armazená-los em cache em um arquivo temporário ou gravá-los diretamente no arquivo de disco sem cache. Quando solicitado a armazenar em cache os dados em um arquivo temporário, o codificador deve criar um arquivo temporário no disco e gravar diretamente nesse arquivo sem armazenar em cache na memória. Quando o utilizador seleciona a opção sem cache, cada quadro deve ser processado em ordem antes que o próximo quadro possa ser criado.

GetContainerFormat

GetContainerFormat é implementado da mesma forma que o método GetContainerFormat em Implementing IWICBitmapDecoder.

ObterInformaçõesDoCodificador

GetEncoderInfo retorna um IWICBitmapEncoderInfo objeto. Para obter o objeto IWICBitmapEncoderInfo, basta passar o GUID do seu codificador para o método CreateComponentInfo emIWICImagingFactorye, em seguida, solicitar a interface IWICBitmapEncoderInfo nele.

Veja o exemplo em Implementing IWICBitmapDecoder em GetDecoderInfo.

CreateNewFrame

CreateNewFrame é a contraparte do codificador do GetFrame em IWICBitmapDecoder. Esse método retorna um IWICBitmapFrameEncode objeto, que é o objeto que realmente serializa os dados de imagem para um quadro específico dentro do contêiner.

Um dos benefícios do Windows Imaging Component (WIC) é que ele fornece uma camada de abstração para aplicativos que permite que eles trabalhem com todos os formatos de imagem da mesma maneira. No entanto, nem todos os formatos de imagem são exatamente iguais. Alguns formatos de imagem têm capacidades que outros não têm. Para que as aplicações possam tirar proveito dessas capacidades únicas, é necessário fornecer uma forma para que o codec as exponha. Este é o objetivo das opções do codificador. Se o codec suportar quaisquer opções de codificador, você deve criar um IPropertyBag2 objeto que exponha as opções do codificador que você suporta e retorná-lo no ppIEncoderOptions parâmetro desse método. O chamador pode então usar esse objeto IPropertyBag2 para determinar quais opções de codificador seu codec suporta. Se o chamador quiser especificar valores para qualquer uma das opções de codificador suportadas, ele atribuirá o valor à propriedade relevante no objeto IPropertyBag2 e o passará para o objeto IWICBitmapFrameEncode recém-criado em seu método Initialize.

Para instanciar um IPropertyBag2 objeto, primeiro você precisa criar uma PROPBAG2 struct para especificar cada opção de codificador que seu codificador suporta e seu tipo de dados para cada propriedade. Em seguida, você deve implementar um objeto IPropertyBag2 que impõe os intervalos de valores para cada propriedade na gravação e reconcilia quaisquer valores conflitantes ou sobrepostos. Para conjuntos simples de opções de codificador não conflitantes, você pode invocar o métodoCreateEncoderPropertyBag, que criará um objeto IPropertyBag2 simples usando as propriedades especificadas em seu PROPBAG2 struct. Você ainda deve impor os intervalos de valores. Para opções de codificador mais avançadas, ou se você precisar reconciliar valores conflitantes, você deve escrever sua própria implementação 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);

O WIC fornece um pequeno conjunto de opções de codificador canônico que são usadas por alguns dos formatos de imagem comuns. Todas as opções canônicas do codificador são opcionais e os codecs não são necessários para suportar nenhuma delas. A razão pela qual eles são fornecidos como opções canônicas é porque muitos aplicativos expõem a interface do usuário para que os usuários especifiquem essas opções ao salvar um arquivo de imagem em um formato que as suporte. Fornecer uma maneira canônica de especificar essas opções torna mais fácil para os aplicativos comunicá-las aos codificadores de forma consistente. As opções canônicas do codificador estão listadas na tabela a seguir.

Opção de codificador VARTYPE Intervalo de valores
Sem perdas VT_BOOL Verdadeiro/Falso
Qualidade de Imagem VT_R4 0.0-1.0
Compressão Qualidade VT_R4 0.0-1.0
BitmapTransform VT_UI1 WICBitmapTransformOptions

 

Se o codec suportar codificação sem perdas, você deve expor a opção de codificador sem perdas como uma maneira de os aplicativos solicitarem que uma imagem seja codificada sem perdas. Se um chamador definir essa propriedade como True, você deverá ignorar a opção ImageQuality e codificar a imagem sem perdas.

A opção ImageQuality permite que um aplicativo especifique o grau de fidelidade com o qual codificar a imagem. Essa opção permite que um usuário faça uma compensação entre qualidade de imagem versus velocidade e/ou tamanho do arquivo. JPEG é um exemplo de um formato de imagem que suporta essa compensação. Um valor de 0,0 indica que a fidelidade é de baixa importância e o codificador deve usar seu algoritmo com mais perdas. Um valor de 1,0 indica que a fidelidade é o mais importante e o codificador deve preservar a maior fidelidade possível. (Dependendo do seu codec, isso pode ser sinônimo da opção Lossless. No entanto, se o codec suportar codificação sem perdas e se a opção Lossless estiver definida como True, a opção ImageQuality deverá ser ignorada.)

A opção CompressionQuality permite que um aplicativo especifique a eficiência da compactação a ser usada ao codificar a imagem. Um algoritmo muito eficiente pode produzir um arquivo de imagem menor com a mesma qualidade de um algoritmo de compressão menos eficiente, mas pode levar mais tempo para codificar. Essa opção permite que um usuário especifique uma compensação entre o tamanho do arquivo versus a velocidade da codificação, preservando o mesmo nível de qualidade. TIFF é um exemplo de um formato de imagem que suporta essa compensação. (Observe que um formato como JPEG suporta diferentes níveis de compactação, mas uma taxa maior de compactação resulta em menor qualidade de imagem. Portanto, um formato de imagem JPEG exporia a opção ImageQuality em vez da opção CompressionQuality.) Um valor de 0,0 para essa opção indica que você deve compactar a imagem o mais rápido possível, sem reduzir a fidelidade, em detrimento de um tamanho de arquivo maior. Um valor de 1,0 indica que você deve criar o menor tamanho de arquivo possível (no mesmo nível de qualidade), independentemente de quanto tempo possa levar para codificá-lo. Um codec pode suportar a opção ImageQuality e a opção CompressionQuality, onde a opção ImageQuality especifica o grau aceitável de perda, e a opção CompressionQuality oferece uma compensação de tamanho/velocidade no nível de qualidade especificado.

A opção BitmapTransform fornece uma maneira para o chamador especificar um ângulo de rotação ou orientação de inversão vertical ou horizontal durante a codificação. O enum WICBitmapTransformOptions usado para especificar a transformação solicitada é o mesmo enum usado ao solicitar uma transformação durante a decodificação por meio da interface IWICBitmapSourceTransform.

Observe que os codificadores não estão limitados às opções canônicas do codificador. O objetivo das opções do codificador é permitir que os codificadores exponham seus recursos, e não há limite para os tipos de recursos que você pode expor. Certifique-se de que as opções do codificador estão bem documentadas. Embora um aplicativo possa usar o pacote de propriedades que você retorna desse método para descobrir os nomes, tipos e intervalos de valores para as opções que você suporta, a única maneira de descobrir seus significados, ou como expô-los na interface do usuário, é a partir de sua documentação.

Confirmar

Commit é o método que você chama depois que todos os dados de imagem e metadados foram serializados no fluxo. Você deve usar esse método para serializar os dados da imagem de visualização no fluxo e quaisquer miniaturas globais, metadados, paleta ou outros itens, se aplicável. Esse método não deve fechar o fluxo de arquivos, porque o aplicativo que abriu o fluxo deve fechá-lo.

A seção sobre o método IWICBitmapFrameEncode:Commit contém detalhes sobre como as opções de cache do IWICBitmapEncoder afetam o comportamento deste método.

SetPreview

SetPreview é usada para criar uma visualização da imagem. Embora não seja estritamente necessário que todas as imagens tenham uma visualização, é altamente recomendável. Câmeras digitais modernas e scanners geram imagens de alta resolução, que tendem a ser muito grandes e, consequentemente, levam um tempo de processamento significativo para decodificar. As imagens da próxima geração de câmeras serão ainda maiores. É uma boa ideia fornecer uma versão menor e de baixa resolução de uma imagem, normalmente em formato JPEG, que possa ser rapidamente decodificada e exibida "instantaneamente" quando um usuário solicitar. Um aplicativo pode solicitar uma visualização antes de solicitar que a imagem real seja decodificada para fornecer uma melhor experiência aos usuários e mostrar-lhes uma representação em tamanho de tela da imagem enquanto aguardam para decodificar a imagem real. Embora os codecs devam fornecer visualizações, os codecs que não suportam IWICBitmapSourceTransform definitivamente devem fazê-lo.

Se você fornecer uma visualização JPEG, não será necessário escrever um codificador JPEG para codificá-la. Você deve delegar ao codificador JPEG fornecido com a plataforma WIC para codificar visualizações e miniaturas.

Referência

IWICBitmapEncoder

IWICBitmapFrameEncode

Conceptual

Interfaces do codificador

Implementação do IWICBitmapCodecProgressNotification (Codificador)

Como escrever um WIC-Enabled CODEC

Visão geral do componente Windows Imaging