`CImage` 類別

發行項
10/12/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`	擷取和 `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.hatlimage.h 。如果您的專案使用 MFC（或它是具有 MFC 支援的 ATL 專案），請在包含之前包含 afxstr.hatlimage.h 。

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