Windows Imaging Component

Noções básicas de Windows Imaging Component

O Microsoft® Windows® Imaging Component (WIC) é uma estrutura extensível para codificar, decodificar e manipular imagens. Originalmente projetado para Windows Vista® e Windows Presentation Foundation (WPF), hoje o WIC não apenas acompanha o Windows Vista e o Microsoft .NET Framework 3.0 e versões posteriores, mas também está disponível como um download para o Windows XP e Windows Server® 2003 para uso em aplicativos nativos.

Uma das várias estruturas nativas eficientes que capacitam o WPF, o WIC, neste contexto, é a estrutura usada na implementação do namespace System.Windows.Media.Imaging. Ele é, no entanto, também perfeitamente adequado para aplicativos nativos escritos em C++ porque fornece uma API simples, mas eficiente, exposta por meio de um conjunto de interfaces COM.

O WIC suporta diferentes formatos de imagem usando um conjunto extensível de codecs de imagens. Cada codec suporta um formato de imagem diferente e normalmente fornece um codificador e um decodificador. O WIC inclui um conjunto de codecs internos para praticamente todos os principais formatos de imagens, incluindo PNG, JPEG, GIF, TIFF, HD Photo (HDP), ICO e, é claro, Windows BMP.

O HDP é o único formato de que você pode nunca ter ouvido falar. Ele era originalmente chamado de Windows Media Photo e foi desenvolvido em conjunto com o Windows Vista para superar algumas das limitações com formatos existentes e fornecer um melhor desempenho e qualidade de imagem superior. Para obter mais informações sobre HDP, consulte a especificação em microsoft.com/whdc/xps/wmphoto.mspx. Felizmente, o WIC fornece um excelente suporte para esse novo formato de imagem, de forma que os aplicativos não precisam saber as especificações dos formatos para usá-los.

Este mês, mostrarei a você como usar o WIC para codificar e decodificar diferentes formatos de imagens e algumas coisas intermediárias. Na próxima vez, explorarei alguns dos recursos mais avançados e mostrarei como estender o WIC com seus próprios codecs de imagens. 

Introdução

A API do WIC consiste de interfaces COM, funções, estruturas e códigos de erros, bem como GUIDs que identificam vários codecs, contêineres e formatos. Todas as declarações necessárias estão incluídas nos arquivos de cabeçalho wincodec.h e wincodecsdk.h fornecidos como parte do Windows SDK (e incluídas com o Visual Studio® 2008). Também será preciso que você vincule à biblioteca WindowsCodecs.lib, que fornece as várias definições necessárias. Você pode adicionar o seguinte ao cabeçalho pré-compilado do seu projeto para torná-lo totalmente disponível:

#include <wincodec.h>
#include <wincodecsdk.h>
#pragma comment(lib, "WindowsCodecs.lib")

Como a API do WIC consiste principalmente de interfaces COM, eu uso a classe CComPtr do ATL (Active Template Library) para tratar da criação e gerenciamento dos ponteiros de interface. Se você desejar fazer o mesmo, precisará incluir também o arquivo do cabeçalho atlbase.h que define a classe de modelo CComPtr:

#include <atlbase.h>

A API do WIC também usa a biblioteca COM, portanto a função CoInitializeEx deve ser chamada em qualquer segmento que usará a API.

Finalmente, a API do WIC usa HRESULTs para descrever erros. As amostras neste artigo usam a macro HR para identificar claramente onde os métodos retornam um HRESULT que precisa ser verificado. Você pode substituir isso por sua própria estratégia de tratamento de erros — seja lançando uma exceção ou retornando você mesmo o HRESULT.

Decodificando imagens

Os decodificadores são representados pela interface IWICBitmapDecoder. O WIC fornece algumas maneiras de criar um objeto decodificador, mas, no mínimo, você pode simplesmente usar um CLSID particular do decodificador para criar uma instância. O exemplo a seguir cria um decodificador para uma imagem TIFF:

CComPtr<IWICBitmapDecoder> decoder;
HR(decoder.CoCreateInstance(CLSID_WICTiffDecoder));

A Figura 1 lista os codecs incluídos com o WIC e os CLSIDs que você pode usar para criar os diferentes decodificadores. Depois que o decodificador é criado, ele precisa ser inicializado com um fluxo contendo os pixels e metadados opcionais em um formato entendido pelo decodificador:

 Figure 1 CLSIDs para codecs internos do WIC

Formato	Decodificador	Codificador
BMP	CLSID_WICBmpDecoder	CLSID_WICBmpEncoder
PNG	CLSID_WICPngDecoder	CLSID_WICPngEncoder
ICO	CLSID_WICIcoDecoder	Não disponível
JPEG	CLSID_WICJpegDecoder	CLSID_WICJpegEncoder
GIF	CLSID_WICGifDecoder	CLSID_WICGifEncoder
TIFF	CLSID_WICTiffDecoder	CLSID_WICTiffEncoder
HDP	CLSID_WICWmpDecoder	CLSID_WICWmpEncoder

CComPtr<IStream> stream;

// Create stream object here...

HR(decoder->Initialize(
  stream,
  WICDecodeMetadataCacheOnDemand));

Discutirei os fluxos mais tarde neste artigo, mas IStream é apenas a interface de fluxo COM tradicional usada por várias APIs, incluindo o analisador XmlLite de que falei na edição de abril de 2007 da MSDN® Magazine (msdn.microsoft.com/msdnmag/issues/07/04/Xml).

O segundo parâmetro para o método Initialize descreve como você gostaria que o decodificador lesse as informações da imagem a partir do fluxo. WICDecodeMetadataCacheOnDemand indica que o decodificador deve apenas ler as informações da imagem a partir do fluxo, conforme necessário. Isso pode ser particularmente útil se o formato da imagem contiver ou suportar vários quadros. A alternativa é WICDecodeMetadataCacheOnLoad, que indica que o decodificador deve armazenar em cache todas as informações da imagem imediatamente. Todas as solicitações subseqüentes para o decodificador seriam então preenchidas diretamente a partir da memória. Isso possui algumas implicações adicionais para códigos gerenciados sobre o que falarei posteriormente.

Com o decodificador inicializado, você pode livremente consultar o decodificador em busca de informações. A coisa mais comum que provavelmente você irá perguntar é o conjunto de quadros que formam uma imagem. Os quadros são os bitmaps reais que contêm os pixels. Você pode pensar no formato da imagem como um contêiner para quadros. Como mencionei, alguns formatos de imagens suportam vários quadros.

A função GetFrameCount é usada para determinar o número de quadros na imagem:

UINT frameCount = 0;
HR(decoder->GetFrameCount(&frameCount));

Dado o número de quadros, quadros individuais podem ser recuperados usando o método GetFrame:

for (UINT index = 0; index < frameCount; ++index)
{
    CComPtr<IWICBitmapFrameDecode> frame;

    HR(decoder->GetFrame(index, &frame));
}

A interface IWICBitmapFrameDecode retornado por GetFrame deriva da interface IWICBitmapSource que representa um bitmap somente leitura. IWICBitmapFrameDecode fornece informações associadas com o quadro, como metadados e perfis de cor. IWICBitmapSource fornece o tamanho e a resolução do bitmap, o formato do pixel e outras características opcionais, como sua tabela de cores. IWICBitmapSource também fornece o método CopyPixels que pode ser usado para realmente ler pixels do bitmap.

Você pode obter as dimensões do quadro expressas em pixels usando o método GetSize:

UINT width = 0;
UINT height = 0;
HR(frame->GetSize(&width, &height));

E pode obter a resolução do quadro expressa em pontos por polegada (dpi) usando o método GetResolution:

double dpiX = 0;
double dpiY = 0;
HR(frame->GetResolution(&dpiX, &dpiY));

Embora a resolução não exerça impacto nos pixels em si, ela afeta como a imagem pode ser exibida ao usar um sistema de coordenadas lógico, como o usado pelo WPF.

O último atributo crítico do quadro é o formato do pixel. Ele descreve o layout dos pixels na memória e também implica o intervalo de cores ou espaço de cor que ele suporta. O método GetPixelFormat retorna o formato do pixel:

GUID pixelFormat = { 0 };
HR(frame->GetPixelFormat(&pixelFormat));

Os formatos do pixel são definidos como GUIDs cujos nomes descrevem bem claramente o layout da memória. Por exemplo, o formato GUID_WICPixelFormat24bppRGB indica que cada pixel usa 24 bits (3 bytes) de armazenamento com canal de 1 byte por cor. Além disso, a ordem das letras R (vermelho), G (verde) e B (azul) indica a ordem dos bytes do menos significativo para o mais significativo. Como um exemplo, o formato GUID_WICPixelFormat32bppBGRA indica que cada pixel usa 32 bits (4 bytes) de armazenamento com canal de 1 byte por cor, bem como 1 byte para o canal alfa. Neste caso, os canais são ordenados com o canal azul (B) sendo menos significativo e o canal alfa (A) sendo o mais significativo.

Os pixels reais podem ser recuperados usando o método CopyPixels.

HRESULT CopyPixels(
  const WICRect* rect,
  UINT stride,
  UINT bufferSize,
  BYTE* buffer);

O parâmetro rect especifica um retângulo dentro do bitmap a copiar. Você pode definir esse parâmetro como zero e ele copiará o bitmap inteiro. Falarei do stride em breve. Os parâmetros buffer e bufferSize indicam onde os pixels serão escritos e quanto espaço há disponível.

O stride pode ser um dos aspectos mais confusos de bitmaps. Stride é a contagem de bytes entre verificações de linha. De modo geral, os bits que formam os pixels de um bitmap são incluídos em linhas. Uma única linha deve ser longa o suficiente para armazenar uma linha dos pixels do bitmap. O stride é o comprimento de uma linha medido em bytes, arredondado para o DWORD mais próximo (4 bytes). Isso permite que bitmaps com menos de 32 bits por pixel (bpp) consumam menos memória enquanto ainda fornecem um bom desempenho. É possível usar a seguinte função para calcular o stride para um determinado bitmap:

UINT GetStride(
  const UINT width, // image width in pixels
  const UINT bitCount) { // bits per pixel
  ASSERT(0 == bitCount % 8);

  const UINT byteCount = bitCount / 8;
  const UINT stride = (width * byteCount + 3) & ~3;

  ASSERT(0 == stride % sizeof(DWORD));
  return stride;
}

Com isso concluído, você pode chamar o método CopyPixels como a seguir, supondo que o quadro representa um bitmap de 32 bpp:

const UINT stride = GetStride(width, 32);
CAtlArray<BYTE> buffer;
VERIFY(buffer.SetCount(stride * height));

HR(frame->CopyPixels(
  0, // entire bitmap
  stride,
  buffer.GetCount(),
  &buffer[0]));

Meu exemplo usa a classe de coleção CAtlArray do ATL para alocar o buffer, mas você pode obviamente usar o armazenamento que desejar. Para tratar de maiores bitmaps com mais eficiência, você pode chamar CopyPixels várias vezes para ler diferentes partes do bitmap.

Codificando imagens

Os codificadores são representados pela interface IWICBitmapEncoder. Como ocorre com os decodificadores, o WIC fornece algumas maneiras de criar codificadores, mas, no mínimo, você pode simplesmente usar um CLSID particular do codificador para criá-lo. Esse código, por exemplo, cria um codificador para uma imagem PNG:

CComPtr<IWICBitmapEncoder> encoder;
HR(encoder.CoCreateInstance(CLSID_WICPngEncoder));

A Figura 1 lista os CLSIDs que você pode usar para criar os diferentes codificadores incluídos com o WIC. Depois que o codificador é criado, ele precisa ser inicializado com um fluxo que finalmente receberá os pixels codificados e metadados opcionais:

CComPtr<IStream> stream;

// Create stream object here...

HR(encoder->Initialize(
  stream,
  WICBitmapEncoderNoCache));

O segundo parâmetro para o método Initialize é menos interessante, uma vez que WICBitmapEncoderNoCache é o único sinalizador suportado agora.

Com o codificador inicializado, você pode agora começar a adicionar quadros. O método CreateNewFrame cria um novo quadro que você pode configurar e no qual é possível escrever pixels:

CComPtr<IWICBitmapFrameEncode> frame;
CComPtr<IPropertyBag2> properties;

HR(encoder->CreateNewFrame(
  &frame,
  &properties));

CreateNewFrame retorna uma interface IWICBitmapFrameEncode representando o novo quadro e uma interface IPropertyBag2. A última é opcional e pode ser usada para determinar qualquer propriedade específica do codificador, como a qualidade da imagem para JPEG ou o algoritmo de compactação para TIFF. Por exemplo, veja como você pode definir a qualidade da imagem para uma imagem JPEG:

PROPBAG2 name = { 0 };
name.dwType = PROPBAG2_TYPE_DATA;
name.vt = VT_R4;
name.pstrName = L"ImageQuality";

CComVariant value(0.75F);

HR(properties->Write(
  1, // property count
  &name,
  &value));

O valor para a qualidade da imagem deve estar entre 0,0 para a qualidade mais baixa possível e 1,0 para a qualidade mais alta possível.

Com as propriedades do codificador definidas, você precisa chamar o método Initialize antes de configurar e escrever no quadro:

HR(frame->Initialize(properties));

A próxima etapa é definir as dimensões e o formato do pixel do novo quadro antes que você possa escrever pixels nele:

HR(frame->SetSize(width, height));
GUID pixelFormat = GUID_WICPixelFormat24bppBGR;
HR(frame->SetPixelFormat(&pixelFormat));
ASSERT(GUID_WICPixelFormat24bppBGR == pixelFormat);

O parâmetro SetPixelFormat é um parâmetro de entrada/saída [in, out]. Na entrada, ele especifica o formato de pixel desejado. Na saída, ele contém o formato de pixel suportado mais próximo. Isso normalmente não é um problema a menos que o formato seja definido em runtime, talvez com base no formato de pixel de outro bitmap.

Escrever pixels no quadro é realizado usando-se o método WritePixels, como exibido aqui:

HRESULT WritePixels(
  UINT lineCount,
  UINT stride,
  UINT bufferSize,
  BYTE* buffer);

O parâmetro lineCount especifica quantas linhas de pixels devem ser escritas. Isso implica que você pode chamar WritePixels várias vezes para escrever o quadro completo. O parâmetro stride indica como os pixels do buffer são incluídos em linhas. Eu descrevi como você pode calcular o stride na seção anterior.

Após ter chamado WritePixels uma ou mais vezes para escrever o quadro completo, você precisa informar ao codificador que o quadro está pronto chamando o método Commit do quadro. E depois de ter confirmado todos os quadros que formam a imagem, você precisa dizer ao codificador que a imagem está pronta para ser salva chamando o método Commit do codificador.

Até aqui, eu tratei das noções básicas da codificação e decodificação de imagens. Antes de seguir adiante, quero concluir com um exemplo simples. A Figura 2 mostra uma função CopyIconToTiff que demonstra como ler os bitmaps individuais que formam um ícone e como copiá-los para uma imagem TIFF com vários quadros.

 Figure 2 CopyIconToTiff

 HRESULT CopyIconToTiff(
   IStream* sourceStream,
   IStream* targetStream) {

  // Prepare the ICO decoder

  CComPtr<IWICBitmapDecoder> decoder;
  HR(decoder.CoCreateInstance(CLSID_WICIcoDecoder));

  HR(decoder->Initialize(
    sourceStream,
    WICDecodeMetadataCacheOnDemand));

  // Prepare the TIFF encoder

  CComPtr<IWICBitmapEncoder> encoder;
  HR(encoder.CoCreateInstance(CLSID_WICTiffEncoder));

  HR(encoder->Initialize(
    targetStream,
    WICBitmapEncoderNoCache));

  UINT frameCount = 0;
  HR(decoder->GetFrameCount(&frameCount));

  for (UINT index = 0; index < frameCount; ++index) {
    // Get the source frame info

    CComPtr<IWICBitmapFrameDecode> sourceFrame;

    HR(decoder->GetFrame(index, &sourceFrame));

    UINT width = 0;
    UINT height = 0;
    HR(sourceFrame->GetSize(&width, &height));

    GUID pixelFormat = { 0 };
    HR(sourceFrame->GetPixelFormat(&pixelFormat));

    // Prepare the target frame

    CComPtr<IWICBitmapFrameEncode> targetFrame;

    HR(encoder->CreateNewFrame(
      &targetFrame,
      0)); // no properties

    HR(targetFrame->Initialize(0)); // no properties

    HR(targetFrame->SetSize(width, height));
    HR(targetFrame->SetPixelFormat(&pixelFormat));

    // Copy the pixels and commit frame

    HR(targetFrame->WriteSource(sourceFrame, 0));
    HR(targetFrame->Commit());
  }

  // Commit image to stream

  HR(encoder->Commit());

  return S OK;
}

Neste exemplo, eu simplifiquei as coisas ainda mais me aproveitando de uma alternativa ao método WritePixels. Em vez de primeiro copiar os pixels do quadro de origem e, em seguida, escrevê-los no quadro de destino, estou usando o método WriteSource que lê os pixels diretamente a partir de uma interface IWICBitmapSource fornecida. Como a interface IWICBitmapFrameDecode deriva de IWICBitmapSource, isso fornece uma solução distinta.

O Imaging Factory do WIC

O WIC fornece um recurso chamado Imaging Factory para criar vários objetos relacionados a ele. Ele é exposto por meio de uma interface IWICImagingFactory e pode ser criado da seguinte maneira:

CComPtr<IWICImagingFactory> factory;
HR(factory.CoCreateInstance(CLSID_WICImagingFactory));

Já mostrei como você pode criar um decodificador para um formato de imagem específico, dado um CLSID que identifica uma implementação. É claro que, como se pode deduzir, seria muito mais útil se não fosse preciso especificar uma implementação particular ou, até mesmo, codificar o formato da imagem.

Felizmente, o WIC fornece a solução. Antes de criar um decodificador, o WIC pode examinar um determinado fluxo em busca de padrões que possam identificar o formato da imagem. Quando uma melhor correspondência for encontrada, ele irá criar o decodificador apropriado e inicializá-lo com o mesmo fluxo. Essa funcionalidade é fornecida pelo método CreateDecoderFromStream:

CComPtr<IWICBitmapDecoder> decoder;

HR(factory->CreateDecoderFromStream(
  stream,
  0, // vendor
  WICDecodeMetadataCacheOnDemand,
  &decoder));

O segundo parâmetro identifica o fornecedor do decodificador. Ele é opcional, mas pode ser útil se você preferir um codec particular do fornecedor. Tenha em mente que isso é apenas uma dica e, se um fornecedor particular não possuir um decodificador adequado instalado, um decodificador ainda será escolhido independentemente do fornecedor.

IWICImagingFactory também fornece os métodos CreateDecoderFromFilename e CreateDecoderFromFileHandle que fornecem a mesma funcionalidade, dado um caminho para um arquivo e um manipulador de arquivos, respectivamente. Como alternativa, você pode criar um decodificador sem especificar um CLSID ou um fluxo, mas em vez disso indicando o formato da imagem. O método CreateDecoder faz exatamente isso:

CComPtr<IWICBitmapDecoder> decoder;

HR(factory->CreateDecoder(
  GUID_ContainerFormatIco,
  0, // vendor
  &decoder));

HR(decoder->Initialize(
  stream,
  WICDecodeMetadataCacheOnDemand));

Da mesma forma, o método CreateEncoder permite que você crie um codificador para um formato de imagem particular sem considerar sua implementação, assim:

CComPtr<IWICBitmapEncoder> encoder;

HR(factory->CreateEncoder(
  GUID_ContainerFormatBmp,
  0, // vendor
  &encoder));

HR(encoder->Initialize(
  stream,
  WICBitmapEncoderNoCache));

A Figura 3 lista os GUIDs identificando os formatos de imagem independentes de implementação, também conhecidos como formatos de contêiner.

 Figure 3 GUIDs de formato de contêiner

Formato	GUID
BMP	GUID_ContainerFormatBmp
PNG	GUID_ContainerFormatPng
ICO	GUID_ContainerFormatIco
JPEG	GUID_ContainerFormatJpeg
GIF	GUID_ContainerFormatGif
TIFF	GUID_ContainerFormatTiff
HDP	GUID_ContainerFormatWmp

Trabalhando com fluxos

Você é livre para fornecer qualquer implementação IStream válida para usar com o WIC. Você pode, por exemplo, usar as funções CreateStreamOnHGlobal ou SHCreateStreamOnFile que descrevi no meu artigo sobre XmlLite ou até mesmo escrever sua própria implementação. O WIC também fornece uma implementação IStream flexível que pode ser útil.

Usando o Imaging Factory que apresentei na seção anterior, você pode criar um objeto de fluxo não-inicializado da seguinte forma:

CComPtr<IWICStream> stream;
HR(factory->CreateStream(&stream));

A interface IWICStream herda de IStream e fornece alguns métodos para associar o fluxo com diferente armazenamento de backup. Por exemplo, você pode usar InitializeFromFilename para criar um fluxo apoiado por um determinado arquivo:

HR(stream->InitializeFromFilename(
  L"file path",
  GENERIC_READ));

Você pode usar também InitializeFromIStreamRegion para criar um fluxo como um subconjunto de outro fluxo ou usar InitializeFromMemory para criar um fluxo sobre um bloco de memória.

WIC via WPF

Como já mencionei, o WIC fornece a estrutura na qual a funcionalidade de imagem do WPF é baseada. As várias classes de imagens são definidas no namespace System.Windows.Media.Imaging. Para mostrar como é fácil usar a partir de código gerenciado, a Figura 4 mostra a função CopyIconToTiff da Figura 2 reescrita em C# usando as classes wrapper do WPF.

 Figure 4 CopyIconToTiff reescrita em C# e WPF

static void CopyIconToTiff(Stream sourceStream,
                           Stream targetStream) {

  IconBitmapDecoder decoder = new IconBitmapDecoder(
    sourceStream,
    BitmapCreateOptions.None,
    BitmapCacheOption.OnDemand);

  TiffBitmapEncoder encoder = new TiffBitmapEncoder();

  foreach (BitmapFrame frame in decoder.Frames) {
    encoder.Frames.Add(frame);
  }

  encoder.Save(targetStream);
}

O valor de BitmapCacheOption.OnDemand corresponde à opção do decodificador WICDecodeMetadataCacheOnDemand usada em código nativo. E, de forma semelhante, o valor de BitmapCacheOption.OnLoad corresponde à opção do decodificador WICDecodeMetadataCacheOnLoad.

Já descrevi como essas opções influenciam quando o decodificador lê as informações da imagem na memória. Existe, no entanto, um efeito colateral adicional do qual você deve estar ciente ao tratar dessas opções em código gerenciado. Considere o que acontece quando você especifica BitmapCacheOption.OnDemand. O decodificador manterá uma referência ao fluxo subjacente e poderá ler a partir dele em algum ponto após o objeto de decodificador do bitmap tiver sido criado. Isso supõe que o fluxo ainda estará disponível. É preciso ter cuidado para que seu aplicativo não feche o fluxo prematuramente. É uma questão de gerenciar a vida útil do fluxo de forma que ele não seja fechado antes que o decodificador tenha terminado com ele.

Isso não afeta o código nativo porque a interface IStream é uma interface COM padrão cuja vida útil é controlada pela contagem de referência. Seu aplicativo pode ter lançado todas as suas referências a ele, mas o decodificador manterá uma enquanto ela for necessária. Além disso, o fluxo é fechado apenas após todos os ponteiros de interface terem sido lançados.

O que vem a seguir?

O WIC fornece uma estrutura incrivelmente eficiente e flexível na qual baseará suas necessidades de imagens. Com um conjunto generoso de codecs e uma API simples, você pode começar a aproveitar vários de seus recursos rapidamente.

Na minha próxima coluna, explorarei alguns dos recursos mais avançados oferecidos pelo WIC. Mostrarei como você pode desenvolver seus próprios codecs e ilustrarei o processo de registro e descoberta, incluindo os recursos de correspondência de padrões, em detalhes. Ainda, corrigirei uma limitação em um dos codecs internos.