`CImage` 類別

發行項
07/05/2024

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`	擷取和 `y`所`x`指定圖元的色彩。
`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）區段的點陣圖;不過，您可以只搭配 DIB 區段使用 Create 或 CImage::Load 。您可以使用將非 DIB 區段點圖附加至 CImage 物件 Attach，但您無法使用下列 CImage 方法，只支援 DIB 區段點圖：

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

若要判斷附加點陣圖是否為 DIB 區段，請呼叫 IsDibSection。

注意

在 Visual Studio .NET 2003 中，此類別會保留所建立物件的計數 CImage 。每當計數進入 0 時，就會自動呼叫函 GdiplusShutdown 式來釋放 GDI+ 所使用的資源。這可確保 DLL 直接或間接建立的任何 CImage 物件一律會正確終結， GdiplusShutdown 而且不會從 DllMain呼叫。

注意

不建議在 DLL 中使用全域 CImage 物件。如果您需要在 DLL 中使用全域 CImage 物件，請呼叫 CImage::ReleaseGDIPlus 以明確釋放 GDI+ 所使用的資源。

CImage 無法選擇新的 CDC。 CImage 為映像建立自己的 HDC 。 HBITMAP因為一次只能選取一個 HDC ，HBITMAP所以無法將與關聯的 CImage 選取到另一個 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 。如果您想要搭配這類函式使用，例如 CMenu::AppendMenu，請使用 CBitmap::FromHandle，傳遞您的 HBITMAPCImage ，並使用傳回的 CBitmap*。CImage

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，請在包含之前包含 atlstr.h atlimage.h。如果您的專案使用 MFC（或它是具有 MFC 支援的 ATL 專案），請在包含之前包含 afxstr.h atlimage.h。

同樣地，您必須先包含 atlimage.h ，才能包含 atlimpl.cpp。若要輕鬆完成這項作業，請在 Visual Studio 2017 和更早版本中納入 atlimage.h pch.h 您的（stdafx.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。

備註

Alpha 混合位圖支援每個圖元的色彩混合。

當設定為的預設值AC_SRC_OVER時bBlendOp，來源位圖會根據來源圖元的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
要執行的點陣作業。點陣作業程式代碼會定義如何結合來源、目的地和模式的位（如目前選取的筆刷所定義）以形成目的地。如需其他點陣作業程序代碼及其描述的清單，請參閱 BitBlt Windows SDK。

pointDest
POINT結構，表示目的矩形的左上角。

nDestWidth
目的地矩形的邏輯單位寬度。

nDestHeight
目的地矩形的高度，以邏輯單位表示。

xSrc
來源矩形左上角的邏輯 X 座標。

ySrc
來源矩形左上角的邏輯 Y 座標。

rectDest
RECT結構，表示目的矩形。

pointSrc
POINT結構，表示來源矩形的左上角。

傳回值

如果成功則不為零，否則為 0。

備註

如需詳細資訊，請參閱 BitBlt Windows SDK 中的。

`CImage::CImage`

建構 CImage 物件。

CImage() throw();

備註

建構物件之後，請呼叫 Create、 Load、 LoadFromResource或 Attach ，將點圖附加至物件。

注意在 Visual Studio 中，此類別會保留所建立物件的計數 CImage 。每當計數進入 0 時，就會自動呼叫函 GdiplusShutdown 式來釋放 GDI+ 所使用的資源。這可確保 DLL 直接或間接建立的任何 CImage 物件一律會正確終結， GdiplusShutdown 而且不會從 DllMain 呼叫。

不建議在 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只有在是 32，且 eCompression 為 BI_RGB時，才能使用 nBPP 。如果指定，建立的影像會針對每個圖元各有 Alpha（透明度）值，並儲存在每個圖元的第 4 個字節中（非 Alpha 32 位影像中未使用）。呼叫時 CImage::AlphaBlend，會自動使用此 Alpha 色板。

注意

在對 CImage::Draw的呼叫中，具有Alpha色板的影像會自動混合至目的地。

傳回值

如果成功則為非零；否則為 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
只有當設定為 BI_BITFIELDS時，才使用 eCompression ，否則必須是 NULL。三 DWORD 個位掩碼數位列的指標，指定每個圖元的哪些位分別用於色彩的紅色、綠色和藍色元件。如需位欄位限制的資訊，請參閱 BITMAPINFOHEADER Windows SDK 中的。

dwFlags
指定點陣圖物件是否有Alpha色板。可以是下列值之零或多個的組合：

createAlphaChannel只有在是 32，且 eCompression 為 BI_RGB時，才能使用 nBPP 。如果指定，建立的影像會針對每個圖元各有 Alpha（透明度）值，並儲存在每個圖元的第 4 個字節中（非 Alpha 32 位影像中未使用）。呼叫時 CImage::AlphaBlend，會自動使用此 Alpha 色板。

注意

在對 CImage::Draw的呼叫中，具有Alpha色板的影像會自動混合至目的地。

傳回值

如果成功，則為 TRUE。否則 FALSE為。

範例

下列範例會使用16位來編碼每個圖元，建立100x100像素點陣圖。在指定的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。

備註

Draw 除非影像包含透明色彩或 Alpha 色板，否則會執行與 StretchBlt相同的作業。在此情況下， 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。 biBitCount如需此值的詳細資訊，請參閱 Windows SDK 中的成員BITMAPINFOHEADER。

`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|...檔案描述 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();

傳回值

TRUE 如果附加的點陣圖是 DIB 區段，則為。否則 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。

備註

載入或pStream所pszFileName指定的映像。

有效的影像類型為 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
要載入之資源的標識碼。

備註

資源必須是類型 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
指定方法用來控制來源和目的地數據組合的前景和背景三元點陣作業程序代碼。背景點陣作業程式代碼會儲存在此值之高階字的高序位元組中;前景點陣作業程式代碼會儲存在此值高序字的低序位元組中;這個值的低序字會被忽略，而且應該是零。如需此方法內容中前景和背景的討論，請參閱 MaskBlt Windows SDK 中的。如需常見點陣作業程式碼的清單，請參閱 BitBlt Windows SDK 中的。

rectDest
結構的參考 RECT ，識別目的地。

pointSrc
POINT結構，表示來源矩形的左上角。

pointMask
POINT結構，表示遮罩位圖的左上角。

pointDest
結構參考 POINT ，這個結構會以邏輯單位識別目的地矩形的左上角。

傳回值

如果成功，則為非零，否則為 0。

備註

此方法僅適用於 Windows NT 4.0 版和更新版本。

`CImage::operator HBITMAP`

使用此運算子取得物件的附加 Windows GDI 句柄 CImage 。這個運算子是一個轉型運算元，可支援直接使用 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 版和更新版本。如需詳細資訊，請參閱 PlgBlt Windows SDK。

`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指定位置的像素設定為、 g和 b所指示r的色彩，以紅色、綠色、藍色（RGB）影像y表示。

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。

備註

如需詳細資訊，請參閱 StretchBlt Windows SDK 中的。

`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`