Classe `CImage`

Artigo
04/03/2023

CImageFornece suporte a bitmap aprimorado, incluindo a capacidade de carregar e salvar imagens em formatos JPEG, GIF, BMP e PNG.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

class CImage

Membros

Construtores públicos

Nome	Descrição
`CImage::CImage`	O construtor .

Métodos públicos

Nome	Descrição
`CImage::AlphaBlend`	Exibe bitmaps que têm pixels transparentes ou semitransparentes.
`CImage::Attach`	Anexa um objeto `HBITMAP` a um objeto `CImage`. Pode ser usado com bitmaps de seção não DIB ou bitmaps de seção DIB.
`CImage::BitBlt`	Copia um bitmap do contexto do dispositivo de origem para este contexto de dispositivo atual.
`CImage::Create`	Cria um bitmap de seção DIB e o anexa ao objeto `CImage` construído anteriormente.
`CImage::CreateEx`	Cria um bitmap de seção DIB (com parâmetros adicionais) e o anexa ao objeto `CImage` construído anteriormente.
`CImage::Destroy`	Desanexa o bitmap do objeto `CImage` e destrói o bitmap.
`CImage::Detach`	Desanexa o bitmap de um objeto `CImage`.
`CImage::Draw`	Copia um bitmap de um retângulo de origem para um retângulo de destino. `Draw` alonga ou compacta o bitmap para se ajustar às dimensões do retângulo de destino, se necessário, e manipula a combinação alfa e as cores transparentes.
`CImage::GetBits`	Recupera um ponteiro para os valores reais de pixel do bitmap.
`CImage::GetBPP`	Recupera os bits por pixel.
`CImage::GetColorTable`	Recupera valores de cor vermelho, verde, azul (RGB) de um intervalo de entradas na tabela de cores.
`CImage::GetDC`	Recupera o contexto do dispositivo no qual o bitmap atual está selecionado.
`CImage::GetExporterFilterString`	Localiza os formatos de imagem disponíveis e suas descrições.
`CImage::GetHeight`	Recupera a altura da imagem atual em pixels.
`CImage::GetImporterFilterString`	Localiza os formatos de imagem disponíveis e suas descrições.
`CImage::GetMaxColorTableEntries`	Recupera o número máximo de entradas na tabela de cores.
`CImage::GetPitch`	Recupera a densidade da imagem atual, em bytes.
`CImage::GetPixel`	Recupera a cor do pixel especificada por `x` e `y`.
`CImage::GetPixelAddress`	Recupera o endereço de determinado pixel.
`CImage::GetTransparentColor`	Recupera a posição da cor transparente na tabela de cores.
`CImage::GetWidth`	Recupera a largura da imagem atual em pixels.
`CImage::IsDIBSection`	Determina se o bitmap anexado é uma seção DIB.
`CImage::IsIndexed`	Indica que as cores de um bitmap são mapeadas para uma paleta indexada.
`CImage::IsNull`	Indica se um bitmap de origem está carregado no momento.
`CImage::IsTransparencySupported`	Indica se o aplicativo dá suporte a bitmaps transparentes.
`CImage::Load`	Carrega uma imagem do arquivo especificado.
`CImage::LoadFromResource`	Carrega uma imagem do recurso especificado.
`CImage::MaskBlt`	Combina os dados de cor para os bitmaps de origem e destino usando a operação de máscara e varredura especificada.
`CImage::PlgBlt`	Executa uma transferência de bloco de bits de um retângulo em um contexto de dispositivo de origem para um paralelogramo em um contexto de dispositivo de destino.
`CImage::ReleaseDC`	Libera o contexto do dispositivo que foi recuperado com `CImage::GetDC`.
`CImage::ReleaseGDIPlus`	Libera recursos usados pelo GDI+. Precisa ser chamado para liberar recursos criados por um objeto `CImage` global.
`CImage::Save`	Salva uma imagem como o tipo especificado. `Save` não pode especificar opções de imagem.
`CImage::SetColorTable`	Define valores de cor RGB vermelho, verde e azul em um intervalo de entradas na tabela de cores da seção DIB.
`CImage::SetPixel`	Define o pixel nas coordenadas especificadas com a cor especificada.
`CImage::SetPixelIndexed`	Define o pixel nas coordenadas especificadas com a cor no índice especificado da paleta.
`CImage::SetPixelRGB`	Define o pixel nas coordenadas especificadas com o valor RGB (vermelho, verde e azul) especificado.
`CImage::SetTransparentColor`	Define o índice da cor a ser tratada como transparente. Somente uma cor em uma paleta pode ser transparente.
`CImage::StretchBlt`	Copia um bitmap de um retângulo de origem em um retângulo de destino, alongando-o ou compactando-o para ajustá-lo às dimensões do retângulo de destino, se necessário.
`CImage::TransparentBlt`	Copia um bitmap com cor transparente do contexto do dispositivo de origem para este contexto atual do dispositivo.

Operadores públicos

Nome	Descrição
`CImage::operator HBITMAP`	Retorna o identificador do Windows anexado ao objeto `CImage`.

Comentários

CImage usa bitmaps que são seções de DIB (bitmap independente do dispositivo) ou não; no entanto, você pode usar Create ou CImage::Load apenas com seções de DIB. Você pode anexar um bitmap de seção não DIB a um objeto CImage usando Attach, mas não pode usar os seguintes métodos CImage, que dão suporte apenas a bitmaps de seção DIB:

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

Para determinar se um bitmap anexado é uma seção DIB, chame IsDibSection.

Observação

No Visual Studio .NET 2003, essa classe mantém uma contagem do número de objetos CImage criados. Sempre que a contagem chegar a 0, a função GdiplusShutdown será chamada automaticamente para liberar recursos usados pelo GDI+. Isso garante que todos os objetos CImage criados direta ou indiretamente por DLLs sejam sempre destruídos corretamente e que GdiplusShutdown não seja chamado de DllMain.

Observação

Não é recomendável usar objetos globais CImage em uma DLL. Se você precisar usar um objeto global CImage em uma DLL, chame CImage::ReleaseGDIPlus para liberar explicitamente os recursos usados pelo GDI+.

CImage não pode ser selecionado em um novo CDC. CImage cria seu próprio HDC para a imagem. Como um HBITMAP só pode ser selecionado em um HDC de cada vez, o HBITMAP associado à CImage ao não pode ser selecionado em outro HDC. Se você precisar de um CDC, recupere o HDC do CImage e repasse-o a CDC::FromHandle.

Exemplos

// Get a CDC for the image
CDC* pDC = CDC::FromHandle(m_myImage.GetDC());

// Use pDC here
pDC->Rectangle(0, 40, 100, 50);
m_myImage.ReleaseDC();

Quando você usa CImage em um projeto MFC, observe quais funções de membro em seu projeto esperam um ponteiro para um objeto CBitmap. Se você quiser usar CImage com essa função, como CMenu::AppendMenu, use CBitmap::FromHandle, passe seu CImage HBITMAP, e use o .CBitmap*

void CMyDlg::OnRButtonDown(UINT nFlags, CPoint point)
{
    UNREFERENCED_PARAMETER(nFlags);

    CBitmap* pBitmap = CBitmap::FromHandle(m_myImage);
    m_pmenuPop->AppendMenu(0, ID_BMPCOMMAND, pBitmap);
    ClientToScreen(&point);
    m_pmenuPop->TrackPopupMenu(TPM_RIGHTBUTTON | TPM_LEFTALIGN, point.x,
    point.y, this);
}

Por meio de CImage, você tem acesso aos bits reais de uma seção DIB. Você pode usar um objeto CImage em qualquer lugar que tenha usado anteriormente um HBITMAP Win32 ou seção DIB.

Você pode usar CImage de MFC ou ATL.

Observação

Ao criar um projeto usando CImage, você precisará definir CString antes de incluir atlimage.h. Se o projeto usar ATL sem MFC, inclua atlstr.h antes de incluir atlimage.h. Se o projeto usar MFC (ou se for um projeto ATL com suporte a MFC), inclua afxstr.h antes de incluir atlimage.h.

Da mesma forma, você precisa incluir atlimage.h antes de incluir atlimpl.cpp. Para fazer isso facilmente, inclua atlimage.h no seu pch.h (stdafx.h no Visual Studio 2017 e anterior).

Requisitos

Cabeçalho: atlimage.h

`CImage::AlphaBlend`

Exibe bitmaps que têm pixels transparentes ou semitransparentes.

BOOL AlphaBlend(
    HDC hDestDC,
    int xDest,
    int yDest,
    BYTE bSrcAlpha = 0xff,
    BYTE bBlendOp = AC_SRC_OVER) const throw();

BOOL AlphaBlend(
    HDC hDestDC,
    const POINT& pointDest,
    BYTE bSrcAlpha = 0xff,
    BYTE bBlendOp = AC_SRC_OVER) const throw();

BOOL AlphaBlend(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    BYTE bSrcAlpha = 0xff,
    BYTE bBlendOp = AC_SRC_OVER);

BOOL AlphaBlend(
    HDC hDestDC,
    const RECT& rectDest,
    const RECT& rectSrc,
    BYTE bSrcAlpha = 0xff,
    BYTE bBlendOp = AC_SRC_OVER);

Parâmetros

hDestDC
Identificador para o contexto do dispositivo de destino.

xDest
A coordenada x, em unidades lógicas, do canto esquerdo superior do retângulo de destino.

yDest
A coordenada y, em unidades lógicas, do canto esquerdo superior do retângulo de destino.

bSrcAlpha
Um valor de transparência alfa a ser usado em todo o bitmap de origem. O 0xff padrão (255) pressupõe que sua imagem seja opaca e que você queira usar apenas valores alfa por pixel.

bBlendOp
A função de combinação alfa para bitmaps de origem e destino, um valor alfa global a ser aplicado a todo o bitmap de origem e as informações de formato para o bitmap de origem. No momento, as funções de combinação de origem e destino estão limitadas a AC_SRC_OVER.

pointDest
Uma referência a uma estrutura POINT que identifica o canto superior esquerdo do retângulo de destino, em unidades lógicas.

nDestWidth
A largura, em unidades lógicas, do retângulo de destino.

nDestHeight
A altura, em unidades lógicas, do retângulo de destino.

xSrc
A coordenada X lógica do canto superior esquerdo do retângulo de origem.

ySrc
A coordenada Y lógica do canto superior esquerdo do retângulo de origem.

nSrcWidth
A largura, em unidades lógicas, do retângulo de origem.

nSrcHeight
A altura, em unidades lógicas, do retângulo de origem.

rectDest
Uma referência a uma estrutura RECT que identifica o destino.

rectSrc
Uma referência a uma estrutura RECT que identifica a origem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Os bitmaps de combinação alfa dão suporte à combinação de cores por pixel.

Quando bBlendOp é definido como o padrão de AC_SRC_OVER, o bitmap de origem é colocado sobre o bitmap de destino com base nos valores alfa dos pixels de origem.

`CImage::Attach`

Anexa hBitmap a um objeto CImage.

void Attach(HBITMAP hBitmap, DIBOrientation eOrientation = DIBOR_DEFAULT) throw();

Parâmetros

hBitmap
Um identificador para um HBITMAP.

eOrientation
Especifica a orientação do bitmap. Um dos seguintes pode ser feito:

DIBOR_DEFAULT A orientação do bitmap é determinada pelo sistema operacional.
DIBOR_BOTTOMUP As linhas do bitmap estão em ordem inversa. Isso faz com que CImage::GetBits retorne um ponteiro perto do final do buffer de bitmap e CImage::GetPitch retorne um número negativo.
DIBOR_TOPDOWN As linhas do bitmap estão na ordem de cima para baixo. Isso faz com que CImage::GetBits retorne um ponteiro para o primeiro byte do buffer de bitmap e CImage::GetPitch retorne um número positivo.

Comentários

O bitmap pode ser um bitmap de seção não DIB ou um bitmap de seção DIB. Confira IsDIBSection para obter uma lista de métodos que você pode usar apenas com bitmaps de seção DIB.

`CImage::BitBlt`

Copia um bitmap do contexto do dispositivo de origem para este contexto de dispositivo atual.

BOOL BitBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    DWORD dwROP = SRCCOPY) const throw();

BOOL BitBlt(
    HDC hDestDC,
    const POINT& pointDest,
    DWORD dwROP = SRCCOPY) const throw();

BOOL BitBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    int xSrc,
    int ySrc,
    DWORD dwROP = SRCCOPY) const throw();

BOOL BitBlt(
    HDC hDestDC,
    const RECT& rectDest,
    const POINT& pointSrc,
    DWORD dwROP = SRCCOPY) const throw();

Parâmetros

hDestDC
O HDC de destino.

xDest
A coordenada X lógica do canto superior esquerdo do retângulo de destino.

yDest
A coordenada Y lógica do canto superior esquerdo do retângulo de destino.

dwROP
A operação de varredura a ser executada. Os códigos de operação de varredura definem exatamente como combinar os bits da origem, do destino e do padrão (conforme definido pelo pincel selecionado no momento) para formar o destino. Confira BitBlt no SDK do Windows para obter uma lista de outros códigos de operação de varredura e suas descrições.

pointDest
Uma estrutura POINT que indica o canto superior esquerdo do retângulo de destino.

nDestWidth
A largura, em unidades lógicas, do retângulo de destino.

nDestHeight
A altura, em unidades lógicas, do retângulo de destino.

xSrc
A coordenada X lógica do canto superior esquerdo do retângulo de origem.

ySrc
A coordenada Y lógica do canto superior esquerdo do retângulo de origem.

rectDest
Uma estrutura RECT que indica o retângulo de destino.

pointSrc
Uma estrutura POINT que indica o canto superior esquerdo do retângulo de origem.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Para obter mais informações, consulte BitBlt no SDK do Windows.

`CImage::CImage`

Constrói um objeto CImage.

CImage() throw();

Comentários

Depois de construir o objeto, chame Create, Load, LoadFromResource ou Attach para anexar um bitmap ao objeto.

Observação No Visual Studio, essa classe mantém uma contagem do número de objetos CImage criados. Sempre que a contagem chegar a 0, a função GdiplusShutdown será chamada automaticamente para liberar recursos usados pelo GDI+. Isso faz com que todos os objetos CImage criados direta ou indiretamente por DLLs sejam sempre destruídos corretamente e que GdiplusShutdown não seja chamado de DllMain.

`CImage::Create`

Cria um bitmap CImage e o anexa ao objeto CImage construído anteriormente.

BOOL Create(
    int nWidth,
    int nHeight,
    int nBPP,
    DWORD dwFlags = 0) throw();

Parâmetros

nWidth
A largura do bitmapCImage, em pixels.

nHeight
A altura do bitmap CImage, em pixels. Se nHeight for positivo, o bitmap será um DIB de baixo para cima e sua origem será o canto inferior esquerdo. Se nHeight for negativo, o bitmap será um DIB de cima para baixo e sua origem será o canto superior esquerdo.

nBPP
O número de bits por pixel no bitmap. Geralmente 4, 8, 16, 24 ou 32. Pode ser 1 para bitmaps ou máscaras monocromáticos.

dwFlags
Especifica se o objeto bitmap tem um canal alfa. Pode ser uma combinação de zero ou mais dos seguintes valores:

createAlphaChannel Só pode ser usado se nBPP for 32 e se eCompression for BI_RGB. Se especificado, a imagem criada tem um valor alfa (transparência) para cada pixel, armazenado no 4º byte de cada pixel (não utilizado em uma imagem não alfa de 32 bits). Esse canal alfa é usado automaticamente ao chamar CImage::AlphaBlend.

Observação

Em chamadas para CImage::Draw, as imagens com um canal alfa são automaticamente combinadas com alfa ao destino.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

`CImage::CreateEx`

Cria um bitmap CImage e o anexa ao objeto CImage construído anteriormente.

BOOL CreateEx(
    int nWidth,
    int nHeight,
    int nBPP,
    DWORD eCompression,
    const DWORD* pdwBitmasks = NULL,
    DWORD dwFlags = 0) throw();

Parâmetros

nWidth
A largura do bitmapCImage, em pixels.

nBPP
O número de bits por pixel no bitmap. Geralmente 4, 8, 16, 24 ou 32. Pode ser 1 para bitmaps ou máscaras monocromáticos.

eCompression
Especifica o tipo de compactação para um bitmap compactado de baixo para cima (DIBs de cima para baixo não podem ser compactados). Pode ser um dos seguintes valores:

BI_RGB O formato não é compactado. A especificação desse valor ao chamar CImage::CreateEx é equivalente a chamar CImage::Create.
BI_BITFIELDS O formato é descompactado e a tabela de cores consiste em três máscaras de cores DWORD que especificam os componentes vermelho, verde e azul, respectivamente, de cada pixel. Isso é válido quando usado com bitmaps de 16 e 32 bpp.

pdwBitfields
Usado somente se eCompression estiver definida como BI_BITFIELDS; caso contrário, ela precisa ser NULL. Um ponteiro para uma matriz de três máscaras de bits DWORD que especifica quais bits de cada pixel são usados nos componentes vermelho, verde e azul da cor, respectivamente. Para saber mais sobre restrições para os campos de bits, confira BITMAPINFOHEADER no SDK do Windows.

dwFlags
Especifica se o objeto bitmap tem um canal alfa. Pode ser uma combinação de zero ou mais dos seguintes valores:

createAlphaChannel Só pode ser usado se nBPP for 32 e se eCompression for BI_RGB. Se especificado, a imagem criada tem um valor alfa (transparência) para cada pixel, armazenado no 4º byte de cada pixel (não utilizado em uma imagem não alfa de 32 bits). Esse canal alfa é usado automaticamente ao chamar CImage::AlphaBlend.

Observação

Em chamadas para CImage::Draw, as imagens com um canal alfa são automaticamente combinadas com alfa ao destino.

Valor de retorno

TRUE se bem-sucedido. Caso contrário, FALSE.

Exemplo

O exemplo a seguir cria um bitmap de 100 x 100 pixels, usando 16 bits para codificar cada pixel. Em determinado pixel de 16 bits, os bits 0-3 codificam o componente vermelho, os bits 4-7 codificam verde e os bits 8-11 codificam azul. Os 4 bits restantes não são utilizados.

DWORD adwBitmasks[3] = { 0x0000000f, 0x000000f0, 0x00000f00 };
m_myImage.CreateEx(100, 100, 16, BI_BITFIELDS, adwBitmasks, 0);

`CImage::Destroy`

Desanexa o bitmap do objeto CImage e destrói o bitmap.

void Destroy() throw();

`CImage::Detach`

Desanexa um bitmap de um objeto CImage.

HBITMAP Detach() throw();

Valor de retorno

Um identificador para o bitmap desanexado ou NULL se nenhum bitmap estiver anexado.

`CImage::Draw`

Copia um bitmap do contexto do dispositivo de origem para o contexto de dispositivo atual.

BOOL Draw(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight) const throw();

BOOL Draw(
    HDC hDestDC,
    const RECT& rectDest,
    const RECT& rectSrc) const throw();

BOOL Draw(
    HDC hDestDC,
    int xDest,
    int yDest) const throw();

BOOL Draw(
    HDC hDestDC,
    const POINT& pointDest) const throw();

BOOL Draw(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight) const throw();

BOOL Draw(
    HDC hDestDC,
    const RECT& rectDest) const throw();

Parâmetros

hDestDC
Um identificador para o contexto do dispositivo de destino.

xDest
A coordenada x, em unidades lógicas, do canto esquerdo superior do retângulo de destino.

yDest
A coordenada y, em unidades lógicas, do canto esquerdo superior do retângulo de destino.

nDestWidth
A largura, em unidades lógicas, do retângulo de destino.

nDestHeight
A altura, em unidades lógicas, do retângulo de destino.

xSrc
A coordenada x, em unidades lógicas, do canto esquerdo superior do retângulo de origem.

ySrc
A coordenada y, em unidades lógicas, do canto esquerdo superior do retângulo de origem.

nSrcWidth
A largura, em unidades lógicas, do retângulo de origem.

nSrcHeight
A altura, em unidades lógicas, do retângulo de origem.

rectDest
Uma referência a uma estrutura RECT que identifica o destino.

rectSrc
Uma referência a uma estrutura RECT que identifica a origem.

pointDest
Uma referência a uma estrutura POINT que identifica o canto superior esquerdo do retângulo de destino, em unidades lógicas.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Draw executa a mesma operação que StretchBlt, a menos que a imagem contenha uma cor transparente ou um canal alfa. Nesse caso, Draw executa a mesma operação que TransparentBlt ou AlphaBlend, conforme a necessidade.

Para versões de Draw que não especificam um retângulo de origem, toda a imagem de origem é o padrão. Para a versão de Draw que não especifica um tamanho para o retângulo de destino, o tamanho da imagem de origem é o padrão e não ocorre nenhum alongamento ou redução.

`CImage::GetBits`

Recupera um ponteiro para os valores de bit reais de determinado pixel em um bitmap.

void* GetBits() throw();

Valor de retorno

Um ponteiro para o buffer de bitmap. Se o bitmap for um DIB de baixo para cima, o ponteiro apontará para perto do final do buffer. Se o bitmap for um DIB de cima para baixo, o ponteiro apontará para o primeiro byte do buffer.

Comentários

Usando esse ponteiro, juntamente com o valor retornado por GetPitch, você pode localizar e alterar pixels individuais em uma imagem.

Observação

Esse método dá suporte apenas a bitmaps de seção DIB; consequentemente, você acessa os pixels de um objeto CImage da mesma maneira que faria com os pixels de uma seção DIB. O ponteiro retornado aponta para o pixel no local (0, 0).

`CImage::GetBPP`

Recupera o valor de bits por pixel.

int GetBPP() const throw();

Valor de retorno

O número de bits por pixel.

Comentários

Esse valor determina o número de bits que define cada pixel e o número máximo de cores no bitmap.

Os bits por pixel geralmente são 1, 4, 8, 16, 24 ou 32. Confira o membro biBitCount de BITMAPINFOHEADER no SDK do Windows para saber mais sobre esse valor.

`CImage::GetColorTable`

Recupera valores de cor vermelho, verde, azul (RGB) de um intervalo de entradas na paleta da seção DIB.

void GetColorTable(
    UINT iFirstColor,
    UINT nColors,
    RGBQUAD* prgbColors) const throw();

Parâmetros

iFirstColor
O índice da tabela de cores da primeira entrada a ser recuperada.

nColors
O número de entradas da tabela de cores a serem recuperadas.

prgbColors
Um ponteiro para a matriz de estruturas RGBQUAD a fim de recuperar as entradas da tabela de cores.

`CImage::GetDC`

Recupera o contexto do dispositivo que atualmente tem a imagem selecionada nele.

HDC GetDC() const throw();

Valor de retorno

Um identificador para um contexto de dispositivo.

Comentários

Em cada chamada para GetDC, você precisa ter uma chamada subsequente para ReleaseDC.

`CImage::GetExporterFilterString`

Localiza formatos de imagem disponíveis para salvar imagens.

static HRESULT GetExporterFilterString(
    CSimpleString& strExporters,
    CSimpleArray<GUID>& aguidFileTypes,
    LPCTSTR pszAllFilesDescription = NULL,
    DWORD dwExclude = excludeDefaultSave,
    TCHAR chSeparator = _T('|'));

Parâmetros

strExporters
Uma referência a um objeto CSimpleString. Confira Comentários para obter mais informações.

aguidFileTypes
Uma matriz de GUIDs, com cada elemento correspondendo a um dos tipos de arquivo na cadeia de caracteres. No exemplo em pszAllFilesDescription abaixo, aguidFileTypes[0] é GUID_NULL e os valores restantes da matriz são os formatos de arquivo de imagem compatíveis com o sistema operacional atual.

Observação

Para obter uma lista completa de constantes, confira Constantes de formato de arquivo de imagem no SDK do Windows.

pszAllFilesDescription
Se esse parâmetro não for NULL, a cadeia de caracteres de filtro terá um filtro adicional no início da lista. Esse filtro terá o valor atual de pszAllFilesDescription como descrição e aceitará arquivos de qualquer extensão com suporte de qualquer outro exportador na lista.

Por exemplo:

//First filter in the list will be titled "All Image Files", and
//will accept files with any extension supported by any exporter.
CImage::GetExporterFilterString(
    strExporters, aguidFileTypes,
_T("All Image Files"));

dwExclude
Conjunto de sinalizadores de bits especificando quais tipos de arquivo devem ser excluídos da lista. Os sinalizadores permitidos são:

excludeGIF = 0x01 Exclui arquivos GIF.
excludeBMP = 0x02 Exclui arquivos BMP (Windows Bitmap).
excludeEMF = 0x04 Exclui arquivos EMF (Metafile Aprimorado).
excludeWMF = 0x08 Exclui arquivos WMF (Windows Metafile).
excludeJPEG = 0x10 Exclui arquivos JPEG.
excludePNG = 0x20 Exclui arquivos PNG.
excludeTIFF = 0x40 Exclui arquivos TIFF.
excludeIcon = 0x80 Exclui arquivos ICO (Ícone do Windows).
excludeOther = 0x80000000 Exclui qualquer outro tipo de arquivo não listado acima.
excludeDefaultLoad = 0 Para carga, todos os tipos de arquivo são incluídos por padrão
excludeDefaultSave = excludeIcon | excludeEMF | excludeWMF Para salvar, esses arquivos são excluídos por padrão porque geralmente têm requisitos especiais.

chSeparator
O separador usado entre os formatos de imagem. Confira Comentários para obter mais informações.

Valor de retorno

Um HRESULT padrão.

Comentários

Você pode transmitir a cadeia de caracteres de formato resultante para o objeto MFC CFileDialog a fim de expor as extensões de arquivo dos formatos de imagem disponíveis na caixa de diálogo Salvar como do arquivo.

O parâmetro strExporter tem o formato:

file description 0|*.ext0|file description 1|*.ext1|...file description N|*.extN||

em que | é o caractere separador especificado por chSeparator. Por exemplo:

"Bitmap format|*.bmp|JPEG format|*.jpg|GIF format|*.gif|PNG format|*.png||"

Use o separador | padrão se você transmite essa cadeia de caracteres para um objeto MFC CFileDialog. Use o separador '\0' nulo se você transmite essa cadeia de caracteres para uma caixa de diálogo Salvar arquivo comum.

`CImage::GetHeight`

Recupera a altura de uma imagem, em pixels.

int GetHeight() const throw();

Valor de retorno

A altura, em pixels, de uma imagem.

`CImage::GetImporterFilterString`

Localiza formatos de imagem disponíveis para carregar imagens.

static HRESULT GetImporterFilterString(
    CSimpleString& strImporters,
    CSimpleArray<GUID>& aguidFileTypes,
    LPCTSTR pszAllFilesDescription = NULL,
    DWORD dwExclude = excludeDefaultLoad,
    TCHAR chSeparator = _T('|'));

Parâmetros

strImporters
Uma referência a um objeto CSimpleString. Confira Comentários para obter mais informações.

aguidFileTypes
Uma matriz de GUIDs, com cada elemento correspondendo a um dos tipos de arquivo na cadeia de caracteres. No exemplo em pszAllFilesDescription abaixo, *aguidFileTypes[0]* é GUID_NULL e os valores restantes da matriz são os formatos de arquivo de imagem compatíveis com o sistema operacional atual.

Observação

Para obter uma lista completa de constantes, confira Constantes de formato de arquivo de imagem no SDK do Windows.

Por exemplo:

//First filter in the list will be titled "All Image Files", and
//will accept files with any extension supported by any importer.
CImage::GetImporterFilterString(
    strImporters, aguidFileTypes,
_T("All Image Files"));

dwExclude
Conjunto de sinalizadores de bits especificando quais tipos de arquivo devem ser excluídos da lista. Os sinalizadores permitidos são:

excludeGIF = 0x01 Exclui arquivos GIF.
excludeBMP = 0x02 Exclui arquivos BMP (Windows Bitmap).
excludeEMF = 0x04 Exclui arquivos EMF (Metafile Aprimorado).
excludeWMF = 0x08 Exclui arquivos WMF (Windows Metafile).
excludeJPEG = 0x10 Exclui arquivos JPEG.
excludePNG = 0x20 Exclui arquivos PNG.
excludeTIFF = 0x40 Exclui arquivos TIFF.
excludeIcon = 0x80 Exclui arquivos ICO (Ícone do Windows).
excludeOther = 0x80000000 Exclui qualquer outro tipo de arquivo não listado acima.
excludeDefaultLoad = 0 Para carga, todos os tipos de arquivo são incluídos por padrão
excludeDefaultSave = excludeIcon | excludeEMF | excludeWMF Para salvar, esses arquivos são excluídos por padrão porque geralmente têm requisitos especiais.

chSeparator
O separador usado entre os formatos de imagem. Confira Comentários para obter mais informações.

Comentários

O parâmetro strImporter tem o formato:

`file description 0|.ext0|file description 1|.ext1|...file description N|*.extN||

em que | é o caractere separador especificado por chSeparator. Por exemplo:

"Bitmap format|*.bmp|JPEG format|*.jpg|GIF format|*.gif|PNG format|*.png||"

`CImage::GetMaxColorTableEntries`

Recupera o número máximo de entradas na tabela de cores.

int GetMaxColorTableEntries() const throw();

Valor de retorno

O número de entradas na tabela de cores.

Comentários

Esse método dá suporte apenas a bitmaps de seção DIB.

`CImage::GetPitch`

Recupera a densidade de uma imagem.

int GetPitch() const throw();

Valor de retorno

A densidade da imagem. Se o valor retornado for negativo, o bitmap será um DIB de baixo para cima e sua origem será o canto inferior esquerdo. Se o valor retornado for positivo, o bitmap será um DIB de cima para baixo e sua origem será o canto superior esquerdo.

Comentários

A densidade é a distância, em bytes, entre dois endereços de memória que representam o início de uma linha de bitmap e o início da próxima linha de bitmap. Como a densidade é medida em bytes, a densidade de uma imagem ajuda você a determinar o formato de pixel. O pitch também pode incluir memória adicional, reservada para o bitmap.

Use GetPitch com GetBits para localizar pixels individuais de uma imagem.

Observação

Esse método dá suporte apenas a bitmaps de seção DIB.

`CImage::GetPixel`

Recupera a cor do pixel no local especificado por x e y.

COLORREF GetPixel(int x, int y) const throw();

Parâmetros

x
A coordenada X do pixel.

y
A coordenada Y do pixel.

Valor de retorno

O valor vermelho, verde, azul (RGB) do pixel. Se o pixel estiver fora da região de recorte atual, o valor retornado será CLR_INVALID.

`CImage::GetPixelAddress`

Recupera o endereço exato de um pixel.

void* GetPixelAddress(int x, int y) throw();

Parâmetros

x
A coordenada X do pixel.

y
A coordenada Y do pixel.

Comentários

O endereço é determinado de acordo com as coordenadas de um pixel, a densidade do bitmap e os bits por pixel.

Para formatos com menos de 8 bits por pixel, esse método retorna o endereço do byte que contém o pixel. Por exemplo, se o formato de imagem tiver 4 bits por pixel, GetPixelAddress retornará o endereço do primeiro pixel no byte e você precisará calcular 2 pixels por byte.

Observação

Esse método dá suporte apenas a bitmaps de seção DIB.

`CImage::GetTransparentColor`

Recupera o local indexado da cor transparente na paleta de cores.

LONG GetTransparentColor() const throw();

Valor de retorno

O índice da cor transparente.

`CImage::GetWidth`

Recupera a largura, em pixels, de uma imagem.

int GetWidth() const throw();

Valor de retorno

A largura do bitmap em pixels.

`CImage::IsDIBSection`

Determina se o bitmap anexado é uma seção DIB.

bool IsDIBSection() const throw();

Valor de retorno

TRUE se o bitmap anexado é uma seção DIB. Caso contrário, FALSE.

Comentários

Se o bitmap não for uma seção DIB, você não poderá usar os seguintes métodos CImage, que dão suporte apenas a bitmaps de seção DIB:

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

`CImage::IsIndexed`

Determina se os pixels de um bitmap são mapeados para uma paleta de cores.

bool IsIndexed() const throw();

Valor de retorno

TRUE se indexado; caso contrário, FALSE.

Comentários

Esse método retornará TRUE somente se o bitmap for de 8 bits (256 cores) ou menos.

Observação

Esse método dá suporte apenas a bitmaps de seção DIB.

`CImage::IsNull`

Determina se um bitmap está carregado no momento.

bool IsNull() const throw();

Comentários

Esse método retornará TRUE se um bitmap não estiver carregado no momento; caso contrário, FALSE.

`CImage::IsTransparencySupported`

Indica se o aplicativo dá suporte a bitmaps transparentes.

static BOOL IsTransparencySupported() throw();

Valor de retorno

Não zero se a plataforma atual der suporte à transparência. Caso contrário, 0.

Comentários

Se o valor retornado não for zero e houver suporte à transparência, uma chamada para AlphaBlend, TransparentBlt ou Draw tratará de cores transparentes.

`CImage::Load`

Carrega uma imagem.

HRESULT Load(LPCTSTR pszFileName) throw();
HRESULT Load(IStream* pStream) throw();

Parâmetros

pszFileName
Um ponteiro para uma cadeia de caracteres contendo o nome do arquivo de imagem a ser carregado.

pStream
Um ponteiro para um fluxo contendo o nome do arquivo de imagem a ser carregado.

Valor de retorno

Um HRESULT padrão.

Comentários

Carrega a imagem especificada por pszFileName ou pStream.

Os tipos de imagem válidos são BMP, GIF, JPEG, PNG e TIFF.

`CImage::LoadFromResource`

Carrega uma imagem de um recurso BITMAP.

void LoadFromResource(
    HINSTANCE hInstance,
    LPCTSTR pszResourceName) throw();

void LoadFromResource(
    HINSTANCE hInstance,
    UINT nIDResource) throw();

Parâmetros

hInstance
Identificador para uma instância do módulo que contém a imagem a ser carregada.

pszResourceName
Um ponteiro para a cadeia de caracteres que contém o nome do recurso com a imagem a ser carregada.

nIDResource
ID do pool de recursos a carregar.

Comentários

O recurso precisa ser do tipo BITMAP.

`CImage::MaskBlt`

Combina os dados de cor para os bitmaps de origem e destino usando a operação de máscara e varredura especificada.

BOOL MaskBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    int xSrc,
    int ySrc,
    HBITMAP hbmMask,
    int xMask,
    int yMask,
    DWORD dwROP = SRCCOPY) const throw();

BOOL MaskBlt(
    HDC hDestDC,
    const RECT& rectDest,
    const POINT& pointSrc,
    HBITMAP hbmMask,
    const POINT& pointMask,
    DWORD dwROP = SRCCOPY) const throw();

BOOL MaskBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    HBITMAP hbmMask,
    DWORD dwROP = SRCCOPY) const throw();

BOOL MaskBlt(
    HDC hDestDC,
    const POINT& pointDest,
    HBITMAP hbmMask,
    DWORD dwROP = SRCCOPY) const throw();

Parâmetros

hDestDC
O identificador para o módulo cujo executável contém o recurso.

xDest
A coordenada x, em unidades lógicas, do canto esquerdo superior do retângulo de destino.

yDest
A coordenada y, em unidades lógicas, do canto esquerdo superior do retângulo de destino.

nDestWidth
A largura, em unidades lógicas, do retângulo de destino e do bitmap de origem.

nDestHeight
A altura, em unidades lógicas, do retângulo de destino e do bitmap de origem.

xSrc
A coordenada X lógica do canto superior esquerdo do bitmap de origem.

ySrc
A coordenada Y lógica do canto superior esquerdo do bitmap de origem.

hbmMask
Identificador para o bitmap de máscara monocromático combinado com o bitmap de cor no contexto do dispositivo de origem.

xMask
O deslocamento horizontal de pixel para o bitmap de máscara especificado pelo parâmetro hbmMask.

yMask
O deslocamento vertical de pixel para o bitmap de máscara especificado pelo parâmetro hbmMask.

dwROP
Especifica os códigos de operação de varredura ternário em primeiro plano e em segundo plano que o método usa para controlar a combinação de dados de origem e de destino. O código de operação de varredura em segundo plano é armazenado no byte de alta ordem da palavra de alta ordem desse valor; o código de operação de varredura em primeiro plano é armazenado no byte de baixa ordem da palavra de alta ordem desse valor; a palavra de baixa ordem desse valor é ignorada e deve ser zero. Para obter uma discussão sobre o primeiro plano e a tela de fundo no contexto desse método, confira MaskBlt no SDK do Windows. Para obter uma lista de códigos de operação de varredura comuns, confira BitBlt no SDK do Windows.

rectDest
Uma referência a uma estrutura RECT que identifica o destino.

pointSrc
Uma estrutura POINT que indica o canto superior esquerdo do retângulo de origem.

pointMask
Uma estrutura POINT que indica o canto superior esquerdo do bitmap de máscara.

pointDest
Uma referência a uma estrutura POINT que identifica o canto superior esquerdo do retângulo de destino, em unidades lógicas.

Valor de retorno

Diferente de zero em caso de êxito; caso contrário, 0.

Comentários

Esse método se aplica somente a Windows NT versões 4.0 e posteriores.

`CImage::operator HBITMAP`

Use esse operador para obter o identificador GDI do Windows anexado do objeto CImage. Esse operador é um operador de conversão, que dá suporte ao uso direto de um objeto HBITMAP.

`CImage::PlgBlt`

Executa uma transferência de bloco de bits de um retângulo em um contexto de dispositivo de origem para um paralelogramo em um contexto de dispositivo de destino.

BOOL PlgBlt(
    HDC hDestDC,
    const POINT* pPoints,
    HBITMAP hbmMask = NULL) const throw();

BOOL PlgBlt(
    HDC hDestDC,
    const POINT* pPoints,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    HBITMAP hbmMask = NULL,
    int xMask = 0,
    int yMask = 0) const throw();

BOOL PlgBlt(
    HDC hDestDC,
    const POINT* pPoints,
    const RECT& rectSrc,
    HBITMAP hbmMask = NULL,
    const POINT& pointMask = CPoint(0, 0)) const throw();

Parâmetros

hDestDC
Um identificador para o contexto do dispositivo de destino.

pPoints
Um ponteiro para uma matriz de três pontos no espaço lógico que identifica três cantos do paralelogramo de destino. O canto superior esquerdo do retângulo de origem é mapeado para o primeiro ponto nessa matriz, o canto superior direito para o segundo ponto nessa matriz e o canto inferior esquerdo para o terceiro ponto. O canto inferior direito do retângulo de origem é mapeado para o quarto ponto implícito no paralelogramo.

hbmMask
Um identificador para um bitmap monocromático opcional que é usado para mascarar as cores do retângulo de origem.

xSrc
A coordenada x, em unidades lógicas, do canto esquerdo superior do retângulo de origem.

ySrc
A coordenada y, em unidades lógicas, do canto esquerdo superior do retângulo de origem.

nSrcWidth
A largura, em unidades lógicas, do retângulo de origem.

nSrcHeight
A altura, em unidades lógicas, do retângulo de origem.

xMask
A coordenada X do canto superior esquerdo do bitmap monocromático.

yMask
A coordenada Y do canto superior esquerdo do bitmap monocromático.

rectSrc
Uma referência a uma estrutura RECT que especifica as coordenadas do retângulo de origem.

pointMask
Uma estrutura POINT que indica o canto superior esquerdo do bitmap de máscara.

Valor de retorno

Diferente de zero em caso de êxito; caso contrário, 0.

Comentários

Se hbmMask identificar um bitmap monocromático válido, PlgBit usará esse bitmap para mascarar os bits de dados de cor do retângulo de origem.

Esse método se aplica somente a Windows NT versões 4.0 e posteriores. Confira PlgBlt no SDK do Windows para informações mais detalhadas.

`CImage::ReleaseDC`

Libera o contexto do dispositivo.

void ReleaseDC() const throw();

Comentários

Como apenas um bitmap pode ser selecionado em um contexto de dispositivo por vez, você precisa chamar ReleaseDC para cada chamada a GetDC.

`CImage::ReleaseGDIPlus`

Libera recursos usados pelo GDI+.

void ReleaseGDIPlus() throw();

Comentários

Esse método precisa ser chamado para liberar recursos alocados por um objeto global CImage. Consulte CImage::CImage.

`CImage::Save`

Salva uma imagem no fluxo ou arquivo especificado no disco.

HRESULT Save(
    IStream* pStream,
    REFGUID guidFileType) const throw();

HRESULT Save(
    LPCTSTR pszFileName,
    REFGUID guidFileType = GUID_NULL) const throw();

Parâmetros

pStream
Um ponteiro para um objeto COM IStream que contém os dados da imagem do arquivo.

pszFileName
Um ponteiro para o nome do arquivo da imagem.

guidFileType
O tipo de arquivo no qual salvar a imagem. Um dos seguintes pode ser feito:

ImageFormatBMP Uma imagem bitmap não compactada.
ImageFormatPNG Uma imagem compactada em formato PNG.
ImageFormatJPEG Uma imagem compactada JPEG.
ImageFormatGIF Uma imagem compactada GIF.

Observação

Para obter uma lista completa de constantes, confira Constantes de formato de arquivo de imagem no SDK do Windows.

Valor de retorno

Um HRESULT padrão.

Comentários

Chame essa função para salvar a imagem usando um nome e um tipo especificados. Se o parâmetro guidFileType não estiver incluído, a extensão de arquivo do nome do arquivo será usada para determinar o formato da imagem. Se nenhuma extensão for fornecida, a imagem será salva no formato BMP.

`CImage::SetColorTable`

Define os valores de cor vermelho, verde, azul (RGB) de um intervalo de entradas na paleta da seção DIB.

void SetColorTable(
    UINT iFirstColor,
    UINT nColors,
    const RGBQUAD* prgbColors) throw();

Parâmetros

iFirstColor
O índice da tabela de cores da primeira entrada a ser definida.

nColors
O número de entradas de tabela de cores a serem definidas.

prgbColors
Um ponteiro para a matriz de estruturas RGBQUAD a fim de definir as entradas da tabela de cores.

Comentários

Esse método dá suporte apenas a bitmaps de seção DIB.

`CImage::SetPixel`

Define a cor de um pixel em determinado local no bitmap.

void SetPixel(int x, int y, COLORREF color) throw();

Parâmetros

x
O local horizontal do pixel a ser definido.

y
O local vertical do pixel a ser definido.

color
A cor para a qual você define o pixel.

Comentários

Esse método falhará se as coordenadas de pixel estiverem fora da área de recorte selecionada.

`CImage::SetPixelIndexed`

Define a cor do pixel para a cor localizada no iIndex na paleta de cores.

void SetPixelIndexed(int x, int y, int iIndex) throw();

Parâmetros

x
O local horizontal do pixel a ser definido.

y
O local vertical do pixel a ser definido.

iIndex
O índice de uma cor na paleta de cores.

`CImage::SetPixelRGB`

Define o pixel nos locais especificados por x e y para as cores indicadas por r, g e b, em uma imagem vermelha, verde, azul (RGB).

void SetPixelRGB(
    int x,
    int y,
    BYTE r,
    BYTE g,
    BYTE b) throw();

Parâmetros

x
O local horizontal do pixel a ser definido.

y
O local vertical do pixel a ser definido.

r
A intensidade da cor vermelha.

g
A intensidade da cor verde.

b
A intensidade da cor azul.

Comentários

Cada um dos parâmetros vermelho, verde e azul é representado por um número entre 0 e 255. Se você definir todos os três parâmetros como zero, a cor resultante combinada será preto. Se você definir todos os três parâmetros como 255, a cor resultante combinada será branco.

`CImage::SetTransparentColor`

Define uma cor em determinado local indexado como transparente.

LONG SetTransparentColor(LONG iTransparentColor) throw();

Parâmetros

iTransparentColor
O índice, em uma paleta de cores, da cor a ser definida como transparente. Se -1, nenhuma cor será definida como transparente.

Valor de retorno

O índice da cor definida anteriormente como transparente.

`CImage::StretchBlt`

Copia um bitmap do contexto do dispositivo de origem para este contexto de dispositivo atual.

BOOL StretchBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    DWORD dwROP = SRCCOPY) const throw();

BOOL StretchBlt(
    HDC hDestDC,
    const RECT& rectDest,
    DWORD dwROP = SRCCOPY) const throw();

BOOL StretchBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    DWORD dwROP = SRCCOPY) const throw();

BOOL StretchBlt(
    HDC hDestDC,
    const RECT& rectDest,
    const RECT& rectSrc,
    DWORD dwROP = SRCCOPY) const throw();