`CBitmap` 类

项目
06/16/2023

封装一个 Windows 图形设备接口 (GDI) 位图并提供成员函数以操作位图。

语法

class CBitmap : public CGdiObject

成员

公共构造函数

名称	描述
`CBitmap::CBitmap`	构造 `CBitmap` 对象。

公共方法

名称	描述
`CBitmap::CreateBitmap`	使用具有指定宽度、高度和位模式的设备相关的内存位图初始化对象。
`CBitmap::CreateBitmapIndirect`	使用具有 `BITMAP` 结构中给定宽度、高度和位模式（如果已指定）的位图初始化对象。
`CBitmap::CreateCompatibleBitmap`	使用位图初始化对象，使它与指定设备兼容。
`CBitmap::CreateDiscardableBitmap`	使用与指定设备兼容的可放弃位图初始化对象。
`CBitmap::FromHandle`	在提供了 Windows `HBITMAP` 位图的句柄时返回指向 `CBitmap` 对象的指针。
`CBitmap::GetBitmap`	使用有关位图的信息填充 `BITMAP` 结构。
`CBitmap::GetBitmapBits`	将指定位图的位复制到指定的缓冲区中。
`CBitmap::GetBitmapDimension`	返回位图的宽度和高度。假定高度和宽度之前已由 `SetBitmapDimension` 成员函数设置。
`CBitmap::LoadBitmap`	通过从应用程序的可执行文件加载命名位图资源并将位图附加到对象来初始化对象。
`CBitmap::LoadMappedBitmap`	加载位图并将颜色映射到当前系统颜色。
`CBitmap::LoadOEMBitmap`	通过加载预定义的 Windows 位图并将该位图附加到对象来初始化对象。
`CBitmap::SetBitmapBits`	将位图的位设置为指定的位值。
`CBitmap::SetBitmapDimension`	以 0.1 毫米为单位为位图分配宽度和高度。

公共运算符

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

注解

若要使用 CBitmap 对象，请构造该对象、使用其中一个初始化成员函数将位图句柄附加到该对象，然后调用该对象的成员函数。

有关使用图形对象（例如 CBitmap）的详细信息，请参阅图形对象。

继承层次结构

CObject

CGdiObject

CBitmap

要求

标头：afxwin.h

`CBitmap::CBitmap`

构造 CBitmap 对象。

CBitmap();

注解

必须使用其中一个初始化成员函数初始化生成的对象。

`CBitmap::CreateBitmap`

初始化具有指定的宽度、高度和位模式的设备相关的内存位图。

BOOL CreateBitmap(
    int nWidth,
    int nHeight,
    UINT nPlanes,
    UINT nBitcount,
    const void* lpBits);

参数

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

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

nPlanes
指定位图中的颜色平面的数量。

nBitcount
指定每个显示像素的颜色位的数量。

lpBits
指向包含的初始位图位值的字节的数组。如果它是 NULL，新位图则未初始化。

返回值

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

注解

对于颜色位图， nPlanes 或 nBitcount 参数应设为 1。如果这些参数均设为 1， CreateBitmap 则会创建一个单色位图。

尽管无法为显示设备直接选择位图，但可以使用 CDC::SelectObject 来选择它作为“内存设备上下文”的当前位图，并使用 CDC::BitBlt 函数将它复制到任何兼容的设备上下文中。

完成通过 CBitmap 函数创建的 CreateBitmap 对象后，首先选择设备上下文中的位图，然后删除 CBitmap 对象。

有关详细信息，请参阅 BITMAP 结构中的 bmBits 字段的说明。 BITMAP 结构是在 CBitmap::CreateBitmapIndirect 成员函数下描述的。

`CBitmap::CreateBitmapIndirect`

初始化具有 lpBitmap 所指向的结构中给定宽度、高度和位模式（如果已指定）的位图。

BOOL CreateBitmapIndirect(LPBITMAP lpBitmap);

参数

lpBitmap
指向包含有关位图的信息的 BITMAP 结构。

返回值

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

备注

尽管无法为显示设备直接选择位图，但可以使用 CDC::SelectObject 来选择它作为“内存设备上下文”的当前位图，并使用 CDC::BitBlt 或 CDC::StretchBlt 函数将它复制到任何兼容的设备上下文中。（CDC::PatBlt 函数可以将当前画笔的位图直接复制到显示设备上下文中。）

如果已使用 GetObject 函数填充了 lpBitmap 参数所指向的 BITMAP 结构，则不会指定位图的位，也不会初始化位图。若要初始化位图，应用程序可以使用 CDC::BitBlt 或 SetDIBits 等函数将位从 CGdiObject::GetObject 的第一个参数标识的位图复制到 CreateBitmapIndirect 创建的位图。

完成通过 CreateBitmapIndirect 函数创建的 CBitmap 对象后，首先选择设备上下文中的位图，然后删除 CBitmap 对象。

`CBitmap::CreateCompatibleBitmap`

初始化与 pDC 指定的设备兼容的位图。

BOOL CreateCompatibleBitmap(
    CDC* pDC,
    int nWidth,
    int nHeight);

参数

pDC
指定设备上下文。

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

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

返回值

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

备注

位图具有与指定设备上下文相同的颜色平面数或相同的每像素位数格式。可以选择它作为与 pDC 指定的设备上下文兼容的任何内存设备的当前位图。

如果 pDC 是内存设备上下文，则返回的位图的格式与该设备上下文中当前选定的位图的格式相同。 “内存设备上下文”是表示显示图面的内存块。它可用于在将内存中的图像复制到兼容设备的实际显示表面之前准备这些图像。

创建内存设备上下文时，GDI 会自动为它选择单色库存位图。

由于彩色内存设备上下文可以选择彩色或单色位图，因此 CreateCompatibleBitmap 函数返回的位图的格式并不总是相同的；但是，非内存设备上下文的兼容位图的格式始终采用设备的格式。

完成通过 CreateCompatibleBitmap 函数创建的 CBitmap 对象后，首先选择设备上下文中的位图，然后删除 CBitmap 对象。

`CBitmap::CreateDiscardableBitmap`

初始化与 pDC 标识的设备上下文兼容的可放弃位图。

BOOL CreateDiscardableBitmap(
    CDC* pDC,
    int nWidth,
    int nHeight);

参数

pDC
指定设备上下文。

nWidth
指定位图的宽度（以位为单位）。

nHeight
指定位图的高度（以位为单位）。

返回值

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

备注

位图具有与指定设备上下文相同的颜色平面数或相同的每像素位数格式。应用程序可以选择此位图作为与 pDC 指定的设备上下文兼容的内存设备的当前位图。

仅当应用程序尚未在显示上下文中选择由此函数创建的位图时，Windows 才能放弃该位图。如果 Windows 在未选择该位图时放弃它，并且应用程序稍后尝试选择它，则 CDC::SelectObject 函数将返回 NULL。

完成通过 CreateDiscardableBitmap 函数创建的 CBitmap 对象后，首先选择设备上下文中的位图，然后删除 CBitmap 对象。

`CBitmap::FromHandle`

在提供了 Windows GDI 位图的句柄时返回指向 CBitmap 对象的指针。

static CBitmap* PASCAL FromHandle(HBITMAP hBitmap);

参数

hBitmap
指定 Windows GDI 位图。

返回值

如果成功，则为指向 CBitmap 对象的指针；否则为 NULL。

注解

如果 CBitmap 对象尚未附加到句柄，则会创建并附加一个临时 CBitmap 对象。此临时 CBitmap 对象仅在应用程序下次在其事件循环中有空闲时间之前有效，届时将删除所有临时图形对象。另一种说法是，临时对象仅在处理一个窗口消息期间有效。

`CBitmap::GetBitmap`

检索附加位图的图像属性。

int GetBitmap(BITMAP* pBitMap);

参数

pBitMap
指向将接收图像属性的 BITMAP 结构的指针。此参数不能为 NULL。

返回值

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

注解

`CBitmap::GetBitmapBits`

将附加位图的位模式复制到指定的缓冲区中。

DWORD GetBitmapBits(
    DWORD dwCount,
    LPVOID lpBits) const;

参数

dwCount
要复制到缓冲区的字节数。

lpBits
指向将接收位图的缓冲区的指针。

返回值

如果方法成功，则为复制到缓冲区的字节数；否则为 0。

备注

使用 CBitmap::GetBitmap 确定所需的缓冲区大小。

`CBitmap::GetBitmapDimension`

返回位图的宽度和高度。

CSize GetBitmapDimension() const;

返回值

位图的宽度和高度（以 0.1 毫米为单位）。高度位于 CSize 对象的 cy 成员中，宽度位于 cx 成员中。如果尚未使用 SetBitmapDimension 设置位图宽度和高度，则返回值为 0。

备注

假定高度和宽度之前已使用 SetBitmapDimension 成员函数进行设置。

`CBitmap::LoadBitmap`

从应用程序的可执行文件加载由 lpszResourceName 命名或由 nIDResource 中的 ID 号标识的位图资源。

BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);

参数

lpszResourceName
指向包含位图资源名称的以 null 终止的字符串。

nIDResource
指定位图资源的资源 ID 号。

返回值

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

注解

加载的位图将附加到 CBitmap 对象。

如果由 lpszResourceName 标识的位图不存在，或者没有足够的内存来加载位图，则该函数返回 0。

可以使用 CGdiObject::DeleteObject 函数删除由 LoadBitmap 函数加载的位图，否则 CBitmap 析构函数将为你删除对象。

注意

在删除对象之前，请确保未在设备上下文中选择该对象。

以下位图已添加到 Windows 版本 3.1 及更高版本中：

OBM_UPARRROWIOBM_DNARROWIOBM_RGARROWIOBM_LFARROWI

在 Windows 版本 3.0 及更早版本的设备驱动程序中找不到这些位图。有关位图的完整列表及其外观的显示，请参阅 Windows SDK。

`CBitmap::LoadMappedBitmap`

调用此成员函数以加载位图并将颜色映射到当前系统颜色。

BOOL LoadMappedBitmap(
    UINT nIDBitmap,
    UINT nFlags = 0,
    LPCOLORMAP lpColorMap = NULL,
    int nMapSize = 0);

参数

nIDBitmap
位图资源的 ID。

nFlags
位图的标志。可以是零或 CMB_MASKED。

lpColorMap
指向包含映射位图所需的颜色信息的 COLORMAP 结构的指针。如果此参数为 NULL，则函数将使用默认颜色映射。

nMapSize
lpColorMap 所指向的颜色映射的数量。

返回值

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

备注

默认情况下，LoadMappedBitmap 将映射按钮字形中常用的颜色。

有关创建映射的位图的信息，请参阅 Windows SDK 中的 Windows 函数 CreateMappedBitmap 和 COLORMAP 结构。

`CBitmap::LoadOEMBitmap`

加载 Windows 使用的预定义的位图。

BOOL LoadOEMBitmap(UINT nIDBitmap);

参数

nIDBitmap
预定义的 Windows 位图的 ID 号。下面列出了 WINDOWS.H 中的可能值：

OBM_BTNCORNERS
OBM_BTSIZE
OBM_CHECK
OBM_CHECKBOXES
OBM_CLOSE
OBM_COMBO
OBM_DNARROW
OBM_DNARROWD
OBM_DNARROWI
OBM_LFARROW
OBM_LFARROWD
OBM_LFARROWI

OBM_MNARROW
OBM_OLD_CLOSE
OBM_OLD_DNARROW
OBM_OLD_LFARROW
OBM_OLD_REDUCE
OBM_OLD_RESTORE
OBM_OLD_RGARROW
OBM_OLD_UPARROW
OBM_OLD_ZOOM
OBM_REDUCE
OBM_REDUCED

OBM_RESTORE
OBM_RESTORED
OBM_RGARROW
OBM_RGARROWD
OBM_RGARROWI
OBM_SIZE
OBM_UPARROW
OBM_UPARROW
OBM_UPARROWD
OBM_ZOOM
OBM_ZOOMD

返回值

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

备注

以 OBM_OLD 开头的位图名称表示 3.0 之前的 Windows 版本使用的位图。

请注意，在包含 WINDOWS.H 之前必须先定义常量 OEMRESOURCE，随后才能使用任何 OBM_ 常量。

`CBitmap::operator HBITMAP`

使用此运算符获取 CBitmap 对象的附加 Windows GDI 句柄。

operator HBITMAP() const;

返回值

如果成功，则由 CBitmap 对象表示的 Windows GDI 对象的句柄；否则 NULL。

备注

此运算符是强制转换运算符，它支持直接使用 HBITMAP 对象。

有关使用图形对象的详细信息，请参阅 Windows SDK 中的图形对象。

`CBitmap::SetBitmapBits`

将位图的位设置为 lpBits 给出的位值。

DWORD SetBitmapBits(
    DWORD dwCount,
    const void* lpBits);

参数

dwCount
指定由 lpBits 指向的字节的数量。

lpBits
指向包含要复制到 CBitmap 对象的像素值的 BYTE 数组。为了使位图能够正确呈现其图像，应设置值的格式以符合创建 CBitmap 实例时指定的高度、宽度和颜色深度值。有关详细信息，请参阅 CBitmap::CreateBitmap。

返回值

用于设置位图位的字节数；如果函数失败，则为 0。

`CBitmap::SetBitmapDimension`

以 0.1 毫米为单位为位图分配宽度和高度。

CSize SetBitmapDimension(
    int nWidth,
    int nHeight);

参数

nWidth
指定位图的宽度（以 0.1 毫米为单位）。

nHeight
指定位图的高度（以 0.1 毫米为单位）。

返回值

之前的位图维度。高度位于 CSize 对象的 cy 成员变量中，宽度位于 cx 成员变量中。

注解

GDI 不使用这些值，但当应用程序调用 GetBitmapDimension 成员函数时返回这些值除外。

另请参阅

MFC 示例 MDI
CGdiObject 类
 层次结构图

通过

CBitmap 类

语法

成员

公共构造函数

公共方法

公共运算符

注解

继承层次结构

要求

CBitmap::CBitmap

注解

CBitmap::CreateBitmap

参数

返回值

注解

CBitmap::CreateBitmapIndirect

参数

返回值

备注

CBitmap::CreateCompatibleBitmap

参数

返回值

备注

CBitmap::CreateDiscardableBitmap

参数

返回值

备注

CBitmap::FromHandle

参数

返回值

注解

CBitmap::GetBitmap

参数

返回值

注解

CBitmap::GetBitmapBits

参数

返回值

备注

CBitmap::GetBitmapDimension

返回值

备注

CBitmap::LoadBitmap

参数

返回值

注解

CBitmap::LoadMappedBitmap

参数

返回值

备注

CBitmap::LoadOEMBitmap

参数

返回值

备注

CBitmap::operator HBITMAP

返回值

备注

CBitmap::SetBitmapBits

参数

返回值

CBitmap::SetBitmapDimension

参数

返回值

注解

另请参阅

反馈

其他资源

`CBitmap` 类

`CBitmap::CBitmap`

`CBitmap::CreateBitmap`

`CBitmap::CreateBitmapIndirect`

`CBitmap::CreateCompatibleBitmap`

`CBitmap::CreateDiscardableBitmap`

`CBitmap::FromHandle`

`CBitmap::GetBitmap`

`CBitmap::GetBitmapBits`

`CBitmap::GetBitmapDimension`

`CBitmap::LoadBitmap`

`CBitmap::LoadMappedBitmap`

`CBitmap::LoadOEMBitmap`

`CBitmap::operator HBITMAP`

`CBitmap::SetBitmapBits`

`CBitmap::SetBitmapDimension`