`CImage` 类

项目
04/03/2023

CImage 提供增强的位图支持，包括能够加载和保存 JPEG、GIF、BMP 和可移植网络图形格式 (PNG) 的图像。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

class CImage

成员

公共构造函数

名称	描述
`CImage::CImage`	构造函数。

公共方法

名称	描述
`CImage::AlphaBlend`	显示具有透明或半透明像素的位图。
`CImage::Attach`	将 `HBITMAP` 附加到 `CImage` 对象。可与非 DIB 节位图或 DIB 节位图一起使用。
`CImage::BitBlt`	将位图从源设备上下文复制到当前设备上下文。
`CImage::Create`	创建 DIB 节位图并将其附加到先前构造的 `CImage` 对象。
`CImage::CreateEx`	创建 DIB 节位图（使用其他参数）并将其附加到先前构造的 `CImage` 对象。
`CImage::Destroy`	从 `CImage` 对象中分离位图并销毁位图。
`CImage::Detach`	从 `CImage` 对象中分离位图。
`CImage::Draw`	将位图从源矩形复制到目标矩形。 `Draw` 根据需要拉伸或压缩位图以适应目标矩形的尺寸，并处理 alpha 混合和透明颜色。
`CImage::GetBits`	检索指向位图实际像素值的指针。
`CImage::GetBPP`	检索每像素位数。
`CImage::GetColorTable`	从颜色表中的条目范围检索红、绿、蓝 (RGB) 颜色值。
`CImage::GetDC`	检索选择当前位图的设备上下文。
`CImage::GetExporterFilterString`	查找可用的图像格式及其说明。
`CImage::GetHeight`	检索当前图像的高度（以像素为单位）。
`CImage::GetImporterFilterString`	查找可用的图像格式及其说明。
`CImage::GetMaxColorTableEntries`	检索颜色表中的最大条目数。
`CImage::GetPitch`	检索当前图像的间距（以字节为单位）。
`CImage::GetPixel`	检索由 `x` 和 `y` 指定的像素的颜色。
`CImage::GetPixelAddress`	检索给定像素的地址。
`CImage::GetTransparentColor`	检索颜色表中透明颜色的位置。
`CImage::GetWidth`	检索当前图像的宽度（以像素为单位）。
`CImage::IsDIBSection`	确定附加位图是否为 DIB 节。
`CImage::IsIndexed`	指示位图的颜色映射到索引调色板。
`CImage::IsNull`	指示当前是否加载源位图。
`CImage::IsTransparencySupported`	指示应用程序是否支持透明位图。
`CImage::Load`	从指定文件加载图像。
`CImage::LoadFromResource`	从指定源加载图像。
`CImage::MaskBlt`	使用指定的蒙板和光栅操作组合源位图和目标位图的颜色数据。
`CImage::PlgBlt`	执行从源设备上下文中的矩形到目标设备上下文中的平行四边形的位块传输。
`CImage::ReleaseDC`	释放使用 `CImage::GetDC` 检索的设备上下文。
`CImage::ReleaseGDIPlus`	释放由 GDI+ 占用的资源。必须调用才能释放由全局 `CImage` 对象创建的资源。
`CImage::Save`	将图像另存为指定类型。 `Save` 无法指定图像选项。
`CImage::SetColorTable`	在 DIB 节颜色表中的一系列条目中设置红、绿、蓝 (RGB) 颜色值。
`CImage::SetPixel`	将指定坐标处的像素设置为指定颜色。
`CImage::SetPixelIndexed`	将指定坐标处的像素设置为调色板指定索引处的颜色。
`CImage::SetPixelRGB`	将指定坐标处的像素设置为指定的红、绿、蓝 (RGB) 值。
`CImage::SetTransparentColor`	将颜色索引设置为透明。调色板中只有一种颜色可以是透明的。
`CImage::StretchBlt`	将位图从源矩形复制到目标矩形，必要时可拉伸或压缩位图以符合目标矩形的尺寸。
`CImage::TransparentBlt`	将带有透明颜色的位图从源设备上下文复制到当前设备上下文。

公共运算符

“属性”	描述
`CImage::operator HBITMAP`	返回附加到 `CImage` 对象的 Windows 句柄。

注解

CImage 采用的位图可以是与设备无关的位图 (DIB) 节，也可能不是；但是，你只能将 Create 或 CImage::Load 用于 DIB 节。可以使用 Attach 将非 DIB 节位图附加到 CImage 对象，但不能使用以下 CImage 方法，该方法仅支持 DIB 节位图：

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

若要确定附加位图是否为 DIB 节，请调用 IsDibSection。

注意

在 Visual Studio .NET 2003 中，此类保留创建的 CImage 对象计数。每当计数为 0 时，都会自动调用 GdiplusShutdown 函数来释放 GDI+ 占用的资源。这可确保 DLL 直接或间接创建的任何 CImage 对象始终被正确销毁，并且不会从 DllMain 中调用 GdiplusShutdown。

注意

不建议在 DLL 中使用全局 CImage 对象。如果需要在 DLL 中使用全局 CImage 对象，请调用 CImage::ReleaseGDIPlus 以显式释放 GDI+ 占用的资源。

不能将 CImage 选择为新的 CDC。 CImage 为图像创建自己的 HDC。因为 HBITMAP 一次只能被选择到一个 HDC 中，所以与 CImage 关联的 HBITMAP 不能被选择到另一个 HDC 中。如果需要 CDC，请从 CImage 中检索 HDC 并将其提供给 CDC::FromHandle。

示例

// 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();

在 MFC 项目中使用 CImage 时，请注意项目中哪些成员函数需要指向 CBitmap 对象的指针。如果要将 CImage 与诸如 CMenu::AppendMenu 之类的函数一起使用，请使用 CBitmap::FromHandle，将其传递给 CImageHBITMAP，并使用返回的 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);
}

通过 CImage，可以访问 DIB 节的实际位。可以在以前使用 Win32 HBITMAP 或 DIB 节的任何位置使用 CImage 对象。

可以从 MFC 或 ATL 使用 CImage。

注意

使用 CImage 创建项目时，必须先定义 CString，然后才能包含 atlimage.h。如果项目在没有 MFC 的情况下使用 ATL，请在包含 atlimage.h 之前包含 atlstr.h。如果项目使用 MFC（或者它是支持 MFC 的 ATL 项目），请在包含 atlimage.h 之前包含 afxstr.h。

同样，在包含 atlimpl.cpp 之前必须包含 atlimage.h。若要轻松完成此操作，请在 pch.h（Visual Studio 2017 及更早版本中为 stdafx.h）中包含 atlimage.h。

要求

标头atlimage.h：

`CImage::AlphaBlend`

显示具有透明或半透明像素的位图。

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

参数

hDestDC
目标设备上下文的句柄。

xDest
目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
目标矩形左上角的 y 坐标（以逻辑单元表示）。

bSrcAlpha
要在整个源位图上使用的 alpha 透明度值。默认 0xff (255) 假定图像不透明，并且你只想使用每像素 alpha 值。

bBlendOp
源位图和目标位图的 alpha 混合函数、要应用于整个源位图的全局 alpha 值，以及源位图的格式信息。源和目标混合函数目前仅限于 AC_SRC_OVER。

pointDest
对标识目标矩形左上角（以逻辑单元表示）的 POINT 结构的引用。

nDestWidth
目标矩形的宽度（以逻辑单元表示）。

nDestHeight
目标矩形的高度（以逻辑单元表示）。

xSrc
源矩形左上角的逻辑 x 坐标。

ySrc
源矩形左上角的逻辑 y 坐标。

nSrcWidth
源矩形的宽度（以逻辑单元表示）。

nSrcHeight
源矩形的高度（以逻辑单元表示）。

rectDest
对 RECT 结构（标识目标）的引用。

rectSrc
对 RECT 结构（标识源）的引用。

返回值

如果成功，则不为 0；否则为 0。

注解

Alpha 混合位图支持按每像素进行颜色混合。

当 bBlendOp 设置为默认值 AC_SRC_OVER 时，源位图将基于源像素的 alpha 值放置在目标位图上。

`CImage::Attach`

将 hBitmap 附加到 CImage 对象。

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

参数

hBitmap
HBITMAP 的句柄。

eOrientation
指定位图的方向。可以是以下值之一：

DIBOR_DEFAULT 位图的方向由操作系统确定。
DIBOR_BOTTOMUP 位图的行按相反顺序排列。这会导致 CImage::GetBits 返回位图缓冲区末端附近的指针，而 CImage::GetPitch 返回一个负数。
DIBOR_TOPDOWN 位图的行按从上到下的顺序排列。这会导致 CImage::GetBits 返回指向位图第一个字节的指针，而 CImage::GetPitch 返回一个正数。

备注

位图可以是非 DIB 节位图，也可以是 DIB 节位图。有关只能与 DIB 节位图一起使用的方法列表，请参阅 IsDIBSection。

`CImage::BitBlt`

将位图从源设备上下文复制到当前设备上下文。

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

参数

hDestDC
目标 HDC。

xDest
目标矩形左上角的逻辑 x 坐标。

yDest
目标矩形左上角的逻辑 y 坐标。

dwROP
要执行的光栅操作。光栅操作代码确切地定义如何将源位、目标位和模式组合在一起（如当前所选画笔所定义的）以形成目标。有关其他光栅操作代码列表及其说明，请参阅 Windows SDK 中的 BitBlt。

pointDest
指示目标矩形左上角的 POINT 结构。

nDestWidth
目标矩形的宽度（以逻辑单元表示）。

nDestHeight
目标矩形的高度（以逻辑单元表示）。

xSrc
源矩形左上角的逻辑 x 坐标。

ySrc
源矩形左上角的逻辑 y 坐标。

rectDest
指示目标矩形的 RECT 结构。

pointSrc
指示源矩形左上角的 POINT 结构。

返回值

如果成功，则不为零，否则为零。

备注

有关详细信息，请参阅 Windows SDK 中的 BitBlt。

`CImage::CImage`

构造 CImage 对象。

CImage() throw();

备注

构造对象后，调用 Create、Load、LoadFromResource 或 Attach 将位图附加到对象。

注意：在 Visual Studio 中，此类保留创建的 CImage 对象计数。每当计数为 0 时，都会自动调用 GdiplusShutdown 函数来释放 GDI+ 占用的资源。这可确保 DLL 直接或间接创建的任何 CImage 对象始终被正确销毁，并且不会从 DllMain 中调用 GdiplusShutdown。

不建议在 DLL 中使用全局 CImage 对象。如果需要在 DLL 中使用全局 CImage 对象，请调用 CImage::ReleaseGDIPlus 以显式释放 GDI+ 占用的资源。

`CImage::Create`

创建 CImage 位图并将其附加到先前构造的 CImage 对象。

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

参数

nWidth
CImage 位图的宽度（以像素为单位）。

nHeight
CImage 位图的高度（以像素为单位）。如果 nHeight 为正数，则位图为自下而上的 DIB，其原点为左下角。如果 nHeight 为负数，则位图为自上而下的 DIB，其原点为左上角。

nBPP
位图中的每像素位数。通常为 4、8、16、24 或 32。对于单色位图或蒙板，可以是 1。

dwFlags
指定位图对象是否有 alpha 通道。可以是零个或多个以下值的组合：

createAlphaChannel 仅当 nBPP 为 32 且 eCompression 为 BI_RGB 时适用。如果指定，所创建的图像对于每个像素都有一个 alpha（透明度）值，存储在每个像素的第 4 字节中（在非 alpha 32 位图像中未使用）。此 alpha 通道在调用 CImage::AlphaBlend 时自动使用。

注意

在调用 CImage::Draw 时，具有 alpha 通道的图像会自动 alpha 混合到目标。

返回值

如果成功，则不为 0；否则为 0。

`CImage::CreateEx`

创建 CImage 位图并将其附加到先前构造的 CImage 对象。

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

参数

nWidth
CImage 位图的宽度（以像素为单位）。

nBPP
位图中的每像素位数。通常为 4、8、16、24 或 32。对于单色位图或蒙板，可以是 1。

eCompression
指定压缩的自下而上位图的压缩类型（无法压缩自上而下的 DIB）。可以是以下其中一个值：

BI_RGB 该格式未压缩。调用 CImage::CreateEx 时指定此值等效于调用 CImage::Create。
BI_BITFIELDS 该格式未压缩，颜色表由三个 DWORD 颜色蒙板组成，分别指定每个像素的红色、绿色和蓝色组件。这在使用 16 和 32-bpp 位图时有效。

pdwBitfields
仅当 eCompression 设置为 BI_BITFIELDS 时使用，否则必须为 NULL。指向三个 DWORD 位掩码数组的指针，指定每个像素的哪些位分别用于颜色的红色、绿色和蓝色组件。有关位字段限制的信息，请参阅 Windows SDK 中的 BITMAPINFOHEADER。

dwFlags
指定位图对象是否有 alpha 通道。可以是零个或多个以下值的组合：

createAlphaChannel 仅当 nBPP 为 32 且 eCompression 为 BI_RGB 时适用。如果指定，所创建的图像对于每个像素都有一个 alpha（透明度）值，存储在每个像素的第 4 字节中（在非 alpha 32 位图像中未使用）。此 alpha 通道在调用 CImage::AlphaBlend 时自动使用。

注意

在调用 CImage::Draw 时，具有 alpha 通道的图像会自动 alpha 混合到目标。

返回值

TRUE 如果成功。否则 FALSE。

示例

以下示例创建一个 100x100 像素位图，使用 16 位对每个像素进行编码。在给定的 16 位像素中，位 0-3 编码红色组件，位 4-7 编码绿色，位 8-11 编码蓝色。其余 4 位未使用。

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

`CImage::Destroy`

从 CImage 对象中分离位图并销毁位图。

void Destroy() throw();

`CImage::Detach`

从 CImage 对象中分离位图。

HBITMAP Detach() throw();

返回值

分离位图的句柄，如果无附加位图，则为 NULL。

`CImage::Draw`

将位图从源设备上下文复制到当前设备上下文。

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

参数

hDestDC
目标设备上下文的句柄。

xDest
目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
目标矩形左上角的 y 坐标（以逻辑单元表示）。

nDestWidth
目标矩形的宽度（以逻辑单元表示）。

nDestHeight
目标矩形的高度（以逻辑单元表示）。

xSrc
源矩形左上角的 x 坐标（以逻辑单元表示）。

ySrc
源矩形左上角的 y 坐标（以逻辑单元表示）。

nSrcWidth
源矩形的宽度（以逻辑单元表示）。

nSrcHeight
源矩形的高度（以逻辑单元表示）。

rectDest
对 RECT 结构（标识目标）的引用。

rectSrc
对 RECT 结构（标识源）的引用。

pointDest
对标识目标矩形左上角（以逻辑单元表示）的 POINT 结构的引用。

返回值

如果成功，则不为 0；否则为 0。

备注

Draw 执行与 StretchBlt 相同的操作，除非图像包含透明颜色或 alpha 通道。在这种情况下，Draw 根据需要执行与 TransparentBlt 或 AlphaBlend 相同的操作。

对于未指定源矩形的 Draw 版本，整个源图像为默认值。对于未指定目标矩形大小的 Draw 版本，源图像的大小为默认值，不会发生拉伸或收缩。

`CImage::GetBits`

检索指向位图中给定像素的实际位值的指针。

void* GetBits() throw();

返回值

指向位图缓冲区的指针。如果位图是自下而上的 DIB，则指针指向缓冲区末端附近。如果位图是自上而下的 DIB，则指针指向缓冲区的第一个字节。

注解

使用此指针以及 GetPitch 返回的值，可以在图像中查找和更改各个像素。

注意

此方法仅支持 DIB 节位图；因此，以访问 DIB 节像素的相同方式访问 CImage 对象的像素。返回的指针指向位置 (0, 0) 处的像素。

`CImage::GetBPP`

检索每像素位数的值。

int GetBPP() const throw();

返回值

每像素位数。

备注

此值确定定义每个像素的位数以及位图中颜色的最大数量。

每像素位数通常为 1、4、8、16、24 或 32。有关此值的详细信息，请参阅 Windows SDK 中 BITMAPINFOHEADER 的 biBitCount 成员。

`CImage::GetColorTable`

从 DIB 节调色板的条目范围检索红、绿、蓝 (RGB) 颜色值。

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

参数

iFirstColor
要检索的第一个条目的颜色表索引。

nColors
要检索的颜色表条目数。

prgbColors
指向 RGBQUAD 结构数组的指针，用于检索颜色表条目。

`CImage::GetDC`

检索当前已选择图像的设备上下文。

HDC GetDC() const throw();

返回值

设备上下文的句柄。

备注

对于 GetDC 的每次调用，必须后续调用 ReleaseDC。

`CImage::GetExporterFilterString`

查找可用于保存图像的图像格式。

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

参数

strExporters
对 CSimpleString 对象的引用。有关详细信息，请参阅注解。

aguidFileTypes
GUID 数组，每个元素对应于字符串中的一种文件类型。在下面的 pszAllFilesDescription 示例中，aguidFileTypes[0] 为 GUID_NULL，其余的数组值为当前操作系统支持的图像文件格式。

注意

有关常量的完整列表，请参阅 Windows SDK 中的图像文件格式常量。

pszAllFilesDescription
如果此参数不是 NULL，则筛选器字符串将在列表开头附加一个筛选器。此筛选器将使用 pszAllFilesDescription 的当前值作为其描述，并接受列表中任何其他导出程序支持的任何扩展文件。

例如：

//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
一组位标志，指定要从列表中排除的文件类型。允许的标志包括：

excludeGIF = 0x01 排除 GIF 文件。
excludeBMP = 0x02 排除 BMP（Windows 位图）文件。
excludeEMF = 0x04 排除 EMF（增强型元文件）文件。
excludeWMF = 0x08 排除 WMF（Windows 元文件）文件。
excludeJPEG = 0x10 排除 JPEG 文件。
excludePNG = 0x20 排除 PNG 文件。
excludeTIFF = 0x40 排除 TIFF 文件。
excludeIcon = 0x80 排除 ICO（Windows 图标）文件。
excludeOther = 0x80000000 排除上面未列出的任何其他文件类型。
excludeDefaultLoad = 0 对于加载，默认情况下包括所有文件类型
excludeDefaultSave = excludeIcon | excludeEMF | excludeWMF 对于保存，默认情况下不包括这些文件，因为它们通常有特殊要求。

chSeparator
图像格式之间使用的分隔符。有关详细信息，请参阅注解。

返回值

一个标准 HRESULT。

备注

可以将生成的格式字符串传递给 MFC CFileDialog 对象，以在“文件另存为”对话框中公开可用图像格式的文件扩展名。

参数 strExporter 的格式如下：

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

其中 | 是 chSeparator 指定的分隔符。例如：

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

如果将此字符串传递给 MFC CFileDialog 对象，请使用默认分隔符 |。如果将此字符串传递给通用“文件保存”对话框，请使用 null 分隔符 '\0'。

`CImage::GetHeight`

检索图像的高度（以像素为单位）。

int GetHeight() const throw();

返回值

图像的高度（以像素为单位）。

`CImage::GetImporterFilterString`

查找可用于加载图像的图像格式。

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

参数

strImporters
对 CSimpleString 对象的引用。有关详细信息，请参阅注解。

aguidFileTypes
GUID 数组，每个元素对应于字符串中的一种文件类型。在下面的 pszAllFilesDescription 示例中，*aguidFileTypes[0]* 为 GUID_NULL，其余的数组值为当前操作系统支持的图像文件格式。

注意

有关常量的完整列表，请参阅 Windows SDK 中的图像文件格式常量。

例如：

//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
一组位标志，指定要从列表中排除的文件类型。允许的标志包括：

excludeGIF = 0x01 排除 GIF 文件。
excludeBMP = 0x02 排除 BMP（Windows 位图）文件。
excludeEMF = 0x04 排除 EMF（增强型元文件）文件。
excludeWMF = 0x08 排除 WMF（Windows 元文件）文件。
excludeJPEG = 0x10 排除 JPEG 文件。
excludePNG = 0x20 排除 PNG 文件。
excludeTIFF = 0x40 排除 TIFF 文件。
excludeIcon = 0x80 排除 ICO（Windows 图标）文件。
excludeOther = 0x80000000 排除上面未列出的任何其他文件类型。
excludeDefaultLoad = 0 对于加载，默认情况下包括所有文件类型
excludeDefaultSave = excludeIcon | excludeEMF | excludeWMF 对于保存，默认情况下不包括这些文件，因为它们通常有特殊要求。

chSeparator
图像格式之间使用的分隔符。有关详细信息，请参阅注解。

备注

可以将生成的格式字符串传递给 MFC CFileDialog 对象，以在“文件打开”对话框中公开可用图像格式的文件扩展名。

参数 strImporter 的格式如下：

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

其中 | 是 chSeparator 指定的分隔符。例如：

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

如果将此字符串传递给 MFC CFileDialog 对象，请使用默认分隔符 |。如果将此字符串传递给通用“文件打开”对话框，请使用 null 分隔符 '\0'。

`CImage::GetMaxColorTableEntries`

检索颜色表中的最大条目数。

int GetMaxColorTableEntries() const throw();

返回值

颜色表中的条目数。

备注

此方法仅支持 DIB 节位图。

`CImage::GetPitch`

检索图像的间距。

int GetPitch() const throw();

返回值

图像的间距。如果返回值为负数，则位图为自下而上的 DIB，其原点为左下角。如果返回值为正数，则位图为自上而下的 DIB，其原点为左上角。

备注

间距是两个内存地址之间的距离（以字节为单位），这两个地址分别表示一个位图行开头和下一个位图行开头。由于间距度量以字节为单位，因此图像的间距有助于确定像素格式。间距还可以包含为位图保留的额外内存。

将 GetPitch 与 GetBits 结合使用查找图像的各个像素。

注意

此方法仅支持 DIB 节位图。

`CImage::GetPixel`

检索 x 和 y 指定的位置的像素颜色。

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

参数

x
像素的 x 坐标。

y
像素的 y 坐标。

返回值

像素的红、绿、蓝 (RGB) 值。如果像素位于当前剪切区域之外，则返回值为 CLR_INVALID。

`CImage::GetPixelAddress`

检索像素的确切地址。

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

参数

x
像素的 x 坐标。

y
像素的 y 坐标。

备注

该地址根据像素的坐标、位图的间距以及每像素位数确定。

对于每像素少于 8 位的格式，此方法返回包含像素的字节的地址。例如，如果图像格式每像素有 4 位，则 GetPixelAddress 返回字节中第一个像素的地址，并且必须计算每字节 2 像素。

注意

此方法仅支持 DIB 节位图。

`CImage::GetTransparentColor`

检索调色板中透明颜色的索引位置。

LONG GetTransparentColor() const throw();

返回值

透明颜色的索引。

`CImage::GetWidth`

检索图像的宽度（以像素为单位）。

int GetWidth() const throw();

返回值

位图的宽度（以像素为单位）。

`CImage::IsDIBSection`

确定附加位图是否为 DIB 节。

bool IsDIBSection() const throw();

返回值

如果附加位图是 DIB 节，则返回 TRUE。否则 FALSE。

备注

如果位图不是 DIB 节，则不能使用以下 CImage 方法，该方法仅支持 DIB 节位图：

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

`CImage::IsIndexed`

确定位图的像素是否映射到调色板。

bool IsIndexed() const throw();

返回值

如已索引，则返回 TRUE；否则返回 FALSE。

备注

仅当位图是 8 位（256 种颜色）或更少时，此方法才会返回 TRUE。

注意

此方法仅支持 DIB 节位图。

`CImage::IsNull`

确定位图当前是否已加载。

bool IsNull() const throw();

备注

如果当前未加载位图，则此方法返回 TRUE；否则返回 FALSE。

`CImage::IsTransparencySupported`

指示应用程序是否支持透明位图。

static BOOL IsTransparencySupported() throw();

返回值

如果当前平台支持透明度，则为非零值。否则为 0。

备注

如果返回值为非零，并且支持透明度，则调用 AlphaBlend、TransparentBlt 或 Draw 将处理透明颜色。

`CImage::Load`

加载图像。

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

参数

pszFileName
指向包含要加载的图像文件名称的字符串的指针。

pStream
指向包含要加载的图像文件名称的流的指针。

返回值

一个标准 HRESULT。

注解

加载由 pszFileName 或 pStream 指定的图像。

有效图像类型包括 BMP、GIF、JPEG、PNG 和 TIFF。

`CImage::LoadFromResource`

从 BITMAP 资源加载图像。

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

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

参数

hInstance
包含要加载的图像的模块实例的句柄。

pszResourceName
指向包含资源名称（其中包含要加载的图像）的字符串的指针。

nIDResource
要加载的资源的 ID。

备注

该资源必须为 BITMAP 类型。

`CImage::MaskBlt`

使用指定的蒙板和光栅操作组合源位图和目标位图的颜色数据。

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

参数

hDestDC
其可执行文件包含资源的模块的句柄。

xDest
目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
目标矩形左上角的 y 坐标（以逻辑单元表示）。

nDestWidth
目标矩形和源位图的宽度（以逻辑单元表示）。

nDestHeight
目标矩形和源位图的高度（以逻辑单元表示）。

xSrc
源位图左上角的逻辑 x 坐标。

ySrc
源位图左上角的逻辑 y 坐标。

hbmMask
与源设备上下文中的颜色位图组合的单色蒙板位图的句柄。

xMask
hbmMask 参数指定的蒙板位图的水平像素偏移量。

yMask
hbmMask 参数指定的蒙板位图的垂直像素偏移量。

dwROP
指定前景和背景三元光栅操作代码，该方法使用这些操作代码来控制源数据和目标数据的组合。背景光栅操作码存储在此值高位字的高位字节中；前景光栅操作码存储在此值高位字的低位字节中；此值的低位字被忽略，应为 0。有关此方法上下文中前景和背景的讨论，请参阅 Windows SDK 中的 MaskBlt。有关常见光栅操作代码列表，请参阅 Windows SDK 中的 BitBlt。

rectDest
对 RECT 结构（标识目标）的引用。

pointSrc
指示源矩形左上角的 POINT 结构。

pointMask
指示蒙板位图左上角的 POINT 结构。

pointDest
对标识目标矩形左上角（以逻辑单元表示）的 POINT 结构的引用。

返回值

如果成功，则返回非零值；否则返回 0。

注解

此方法仅适用于 Windows NT 版本 4.0 及更高版本。

`CImage::operator HBITMAP`

使用此运算符获取 CImage 对象的附加 Windows GDI 句柄。此运算符是强制转换运算符，它支持直接使用 HBITMAP 对象。

`CImage::PlgBlt`

执行从源设备上下文中的矩形到目标设备上下文中的平行四边形的位块传输。

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

参数

hDestDC
目标设备上下文的句柄。

pPoints
指向逻辑空间中三个点的数组的指针，该数组标识目标平行四边形的三个角。源矩形的左上角映射到此数组的第一个点，右上角映射到此数组的第二个点，左下角映射到第三个点。源矩形的右下角映射到平行四边形中隐含的第四个点。

hbmMask
用于屏蔽源矩形颜色的可选单色位图的句柄。

xSrc
源矩形左上角的 x 坐标（以逻辑单元表示）。

ySrc
源矩形左上角的 y 坐标（以逻辑单元表示）。

nSrcWidth
源矩形的宽度（以逻辑单元表示）。

nSrcHeight
源矩形的高度（以逻辑单元表示）。

xMask
单色位图左上角的 x 坐标。

yMask
单色位图左上角的 y 坐标。

rectSrc
对指定源矩形坐标的 RECT 结构的引用。

pointMask
指示蒙板位图左上角的 POINT 结构。

返回值

如果成功，则返回非零值；否则返回 0。

备注

如果 hbmMask 标识有效的单色位图，则 PlgBit 使用此位图来屏蔽源矩形中的颜色数据位。

此方法仅适用于 Windows NT 版本 4.0 及更高版本。有关更多详细信息，请参阅 Windows SDK 中的 PlgBlt。

`CImage::ReleaseDC`

释放设备上下文。

void ReleaseDC() const throw();

备注

因为一次只能在设备上下文中选择一个位图，所以每次调用 GetDC 时都必须调用 ReleaseDC。

`CImage::ReleaseGDIPlus`

释放由 GDI+ 占用的资源。

void ReleaseGDIPlus() throw();

备注

必须调用此方法以释放由全局 CImage 对象分配的资源。请参阅 CImage::CImage。

`CImage::Save`

将图像保存到磁盘上的指定流或文件。

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

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

参数

pStream
指向包含文件图像数据的 COM IStream 对象的指针。

pszFileName
指向图像文件名的指针。

guidFileType
保存图像的文件类型。可以是以下值之一：

ImageFormatBMP 未压缩的位图图像。
ImageFormatPNG 可移植网络图形格式 (PNG) 压缩图像。
ImageFormatJPEG JPEG 压缩图像。
ImageFormatGIF GIF 压缩图像。

注意

有关常量的完整列表，请参阅 Windows SDK 中的图像文件格式常量。

返回值

一个标准 HRESULT。

备注

调用此函数以使用指定的名称和类型保存图像。如果未包含 guidFileType 参数，则文件名的文件扩展名将用于确定图像格式。如果未提供扩展名，则图像将以 BMP 格式保存。

`CImage::SetColorTable`

为 DIB 节调色板中的条目范围设置红、绿、蓝 (RGB) 颜色值。

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

参数

iFirstColor
要设置的第一个条目的颜色表索引。

nColors
要设置的颜色表条目数。

prgbColors
指向 RGBQUAD 结构数组的指针，用于设置颜色表条目。

备注

此方法仅支持 DIB 节位图。

`CImage::SetPixel`

设置位图中给定位置像素的颜色。

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

参数

x
要设置的像素的水平位置。

y
要设置的像素的垂直位置。

color
设置像素的颜色。

备注

如果像素坐标位于所选剪切区域之外，此方法将失败。

`CImage::SetPixelIndexed`

将像素颜色设置为位于调色板中 iIndex 的颜色。

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

参数

x
要设置的像素的水平位置。

y
要设置的像素的垂直位置。

iIndex
调色板中颜色的索引。

`CImage::SetPixelRGB`

将 x 和 y 指定位置的像素设置为 r、g 和 b 所表示的颜色，采用红、绿、蓝 (RGB) 图像。

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

参数

x
要设置的像素的水平位置。

y
要设置的像素的垂直位置。

r
红色的强度。

g
绿色的强度。

b
蓝色的强度。

注解

红、绿和蓝参数分别由一个 0 到 255 之间的数字表示。如果将所有三个参数都设置为零，那么组合生成的颜色为黑色。如果将所有三个参数都设置为 255，则组合生成的颜色为白色。

`CImage::SetTransparentColor`

将给定索引位置的颜色设置为透明。

LONG SetTransparentColor(LONG iTransparentColor) throw();

参数

iTransparentColor
在调色板中，要设置为透明的颜色的索引。如果为 -1，则不会将颜色设置为透明。

返回值

先前设置为透明的颜色的索引。

`CImage::StretchBlt`

将位图从源设备上下文复制到当前设备上下文。

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

参数

hDestDC
目标设备上下文的句柄。

xDest
目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
目标矩形左上角的 y 坐标（以逻辑单元表示）。

nDestWidth
目标矩形的宽度（以逻辑单元表示）。

nDestHeight
目标矩形的高度（以逻辑单元表示）。

rectDest
对 RECT 结构（标识目标）的引用。

xSrc
源矩形左上角的 x 坐标（以逻辑单元表示）。

ySrc
源矩形左上角的 y 坐标（以逻辑单元表示）。

nSrcWidth
源矩形的宽度（以逻辑单元表示）。

nSrcHeight
源矩形的高度（以逻辑单元表示）。

rectSrc
对 RECT 结构（标识源）的引用。

返回值

如果成功，则返回非零值；否则返回 0。

备注

有关详细信息，请参阅 Windows SDK 中的 StretchBlt。

`CImage::TransparentBlt`

将位图从源设备上下文复制到当前设备上下文。

BOOL TransparentBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    UINT crTransparent = CLR_INVALID) const throw();

BOOL TransparentBlt(
    HDC hDestDC,
    const RECT& rectDest,
    UINT crTransparent = CLR_INVALID) const throw();

BOOL TransparentBlt(
    HDC hDestDC,
    int xDest,
    int yDest,
    int nDestWidth,
    int nDestHeight,
    int xSrc,
    int ySrc,
    int nSrcWidth,
    int nSrcHeight,
    UINT crTransparent = CLR_INVALID) const throw();

BOOL TransparentBlt(
    HDC hDestDC,
    const RECT& rectDest,
    const RECT& rectSrc,
    UINT crTransparent = CLR_INVALID) const throw();

参数

hDestDC
目标设备上下文的句柄。

xDest
目标矩形左上角的 x 坐标（以逻辑单元表示）。

yDest
目标矩形左上角的 y 坐标（以逻辑单元表示）。

nDestWidth
目标矩形的宽度（以逻辑单元表示）。

nDestHeight
目标矩形的高度（以逻辑单元表示）。

crTransparent
源位图中要视为透明的颜色。默认情况下为 CLR_INVALID，表示应使用当前设置为图像透明颜色的颜色。

rectDest
对 RECT 结构（标识目标）的引用。

xSrc
源矩形左上角的 x 坐标（以逻辑单元表示）。

ySrc
源矩形左上角的 y 坐标（以逻辑单元表示）。

nSrcWidth
源矩形的宽度（以逻辑单元表示）。

nSrcHeight
源矩形的高度（以逻辑单元表示）。

rectSrc
对 RECT 结构（标识源）的引用。

返回值

如果成功，则为 TRUE；否则为 FALSE。

注解

TransparentBlt 支持每像素 4 位和每像素 8 位的源位图。使用 CImage::AlphaBlend 指定每像素 32 位位图的透明度。

示例

// Performs a transparent blit from the source image to the destination
// image using the images' current transparency settings
BOOL TransparentBlt(CImage* pSrcImage, CImage* pDstImage,
       int xDest, int yDest, int nDestWidth, int nDestHeight)
{
    HDC hDstDC = NULL;
    BOOL bResult;

    if(pSrcImage == NULL || pDstImage == NULL)
    {
        // Invalid parameter
        return FALSE;
    }

    // Obtain a DC to the destination image
    hDstDC = pDstImage->GetDC();
    // Perform the blit
    bResult = pSrcImage->TransparentBlt(hDstDC, xDest, yDest, nDestWidth, nDestHeight);

    // Release the destination DC
    pDstImage->ReleaseDC();

    return bResult;
}

另请参阅

MMXSwarm 示例
 SimpleImage 示例
 与设备无关的位图
 CreateDIBSection
ATL COM 桌面组件
 与设备无关的位图

CImage 类

语法

成员

公共构造函数

公共方法

公共运算符

注解

示例

要求

CImage::AlphaBlend

参数

返回值

注解

CImage::Attach

参数

备注

CImage::BitBlt

参数

返回值

备注

CImage::CImage

备注

CImage::Create

参数

返回值

CImage::CreateEx

参数

返回值

示例

CImage::Destroy

CImage::Detach

返回值

CImage::Draw

参数

返回值

备注

CImage::GetBits

返回值

注解

CImage::GetBPP

返回值

备注

CImage::GetColorTable

参数

CImage::GetDC

返回值

备注

CImage::GetExporterFilterString

参数

返回值

备注

CImage::GetHeight

返回值

CImage::GetImporterFilterString

参数

备注

CImage::GetMaxColorTableEntries

返回值

备注

CImage::GetPitch

返回值

备注

CImage::GetPixel

参数

返回值

CImage::GetPixelAddress

参数

备注

CImage::GetTransparentColor

返回值

CImage::GetWidth

返回值

CImage::IsDIBSection

返回值

备注

CImage::IsIndexed

返回值

备注

CImage::IsNull

备注

`CImage` 类

`CImage::AlphaBlend`

`CImage::Attach`

`CImage::BitBlt`

`CImage::CImage`

`CImage::Create`

`CImage::CreateEx`

`CImage::Destroy`

`CImage::Detach`

`CImage::Draw`

`CImage::GetBits`

`CImage::GetBPP`

`CImage::GetColorTable`

`CImage::GetDC`

`CImage::GetExporterFilterString`

`CImage::GetHeight`

`CImage::GetImporterFilterString`

`CImage::GetMaxColorTableEntries`

`CImage::GetPitch`

`CImage::GetPixel`

`CImage::GetPixelAddress`

`CImage::GetTransparentColor`

`CImage::GetWidth`

`CImage::IsDIBSection`

`CImage::IsIndexed`

`CImage::IsNull`

`CImage::IsTransparencySupported`

`CImage::Load`

`CImage::LoadFromResource`

`CImage::MaskBlt`

`CImage::operator HBITMAP`

`CImage::PlgBlt`

`CImage::ReleaseDC`

`CImage::ReleaseGDIPlus`

`CImage::Save`

`CImage::SetColorTable`

`CImage::SetPixel`

`CImage::SetPixelIndexed`

`CImage::SetPixelRGB`

`CImage::SetTransparentColor`

`CImage::StretchBlt`

`CImage::TransparentBlt`