`CImage` Class

Article
09/16/2022

CImage provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

class CImage

Members

Public Constructors

Name	Description
`CImage::CImage`	The constructor.

Public Methods

Name	Description
`CImage::AlphaBlend`	Displays bitmaps that have transparent or semitransparent pixels.
`CImage::Attach`	Attaches an `HBITMAP` to a `CImage` object. Can be used with either non-DIB section bitmaps or DIB section bitmaps.
`CImage::BitBlt`	Copies a bitmap from the source device context to this current device context.
`CImage::Create`	Creates a DIB section bitmap and attaches it to the previously constructed `CImage` object.
`CImage::CreateEx`	Creates a DIB section bitmap (with additional parameters) and attaches it to the previously constructed `CImage` object.
`CImage::Destroy`	Detaches the bitmap from the `CImage` object and destroys the bitmap.
`CImage::Detach`	Detaches the bitmap from a `CImage` object.
`CImage::Draw`	Copies a bitmap from a source rectangle into a destination rectangle. `Draw` stretches or compresses the bitmap to fit the dimensions of the destination rectangle, if necessary, and handles alpha blending and transparent colors.
`CImage::GetBits`	Retrieves a pointer to the actual pixel values of the bitmap.
`CImage::GetBPP`	Retrieves the bits per pixel.
`CImage::GetColorTable`	Retrieves red, green, blue (RGB) color values from a range of entries in the color table.
`CImage::GetDC`	Retrieves the device context into which the current bitmap is selected.
`CImage::GetExporterFilterString`	Finds the available image formats and their descriptions.
`CImage::GetHeight`	Retrieves the height of the current image in pixels.
`CImage::GetImporterFilterString`	Finds the available image formats and their descriptions.
`CImage::GetMaxColorTableEntries`	Retrieves the maximum number of entries in the color table.
`CImage::GetPitch`	Retrieves the pitch of the current image, in bytes.
`CImage::GetPixel`	Retrieves the color of the pixel specified by `x` and `y`.
`CImage::GetPixelAddress`	Retrieves the address of a given pixel.
`CImage::GetTransparentColor`	Retrieves the position of the transparent color in the color table.
`CImage::GetWidth`	Retrieves the width of the current image in pixels.
`CImage::IsDIBSection`	Determines if the attached bitmap is a DIB section.
`CImage::IsIndexed`	Indicates that a bitmap's colors are mapped to an indexed palette.
`CImage::IsNull`	Indicates if a source bitmap is currently loaded.
`CImage::IsTransparencySupported`	Indicates whether the application supports transparent bitmaps.
`CImage::Load`	Loads an image from the specified file.
`CImage::LoadFromResource`	Loads an image from the specified resource.
`CImage::MaskBlt`	Combines the color data for the source and destination bitmaps using the specified mask and raster operation.
`CImage::PlgBlt`	Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context.
`CImage::ReleaseDC`	Releases the device context that was retrieved with `CImage::GetDC`.
`CImage::ReleaseGDIPlus`	Releases resources used by GDI+. Must be called to free resources created by a global `CImage` object.
`CImage::Save`	Saves an image as the specified type. `Save` cannot specify image options.
`CImage::SetColorTable`	Sets red, green, blue RGB) color values in a range of entries in the color table of the DIB section.
`CImage::SetPixel`	Sets the pixel at the specified coordinates to the specified color.
`CImage::SetPixelIndexed`	Sets the pixel at the specified coordinates to the color at the specified index of the palette.
`CImage::SetPixelRGB`	Sets the pixel at the specified coordinates to the specified red, green, blue (RGB) value.
`CImage::SetTransparentColor`	Sets the index of the color to be treated as transparent. Only one color in a palette can be transparent.
`CImage::StretchBlt`	Copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary.
`CImage::TransparentBlt`	Copies a bitmap with transparent color from the source device context to this current device context.

Public Operators

Name	Description
`CImage::operator HBITMAP`	Returns the Windows handle attached to the `CImage` object.

Remarks

CImage takes bitmaps that are either device-independent bitmap (DIB) sections or not; however, you can use Create or CImage::Load with only DIB sections. You can attach a non-DIB section bitmap to a CImage object using Attach, but then you cannot use the following CImage methods, which support only DIB section bitmaps:

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

To determine if an attached bitmap is a DIB section, call IsDibSection.

Note

In Visual Studio .NET 2003, this class keeps a count of the number of CImage objects created. Whenever the count goes to 0, the function GdiplusShutdown is automatically called to release resources used by GDI+. This ensures that any CImage objects created directly or indirectly by DLLs are always destroyed properly and that GdiplusShutdown is not called from DllMain.

Note

Using global CImage objects in a DLL is not recommended. If you need to use a global CImage object in a DLL, call CImage::ReleaseGDIPlus to explicitly release resources used by GDI+.

CImage cannot be selected into a new CDC. CImage creates its own HDC for the image. Because an HBITMAP can only be selected into one HDC at a time, the HBITMAP associated with the CImage cannot be selected into another HDC. If you need a CDC, retrieve the HDC from the CImage and give it to CDC::FromHandle.

Examples

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

When you use CImage in an MFC project, note which member functions in your project expect a pointer to a CBitmap object. If you want to use CImage with such a function, like CMenu::AppendMenu, use CBitmap::FromHandle, pass it your CImage HBITMAP, and use the returned 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);
}

Through CImage, you have access to the actual bits of a DIB section. You can use a CImage object anywhere you previously used a Win32 HBITMAP or DIB section.

You can use CImage from either MFC or ATL.

Note

When you create a project using CImage, you must define CString before you include atlimage.h. If your project uses ATL without MFC, include atlstr.h before you include atlimage.h. If your project uses MFC (or if it is an ATL project with MFC support), include afxstr.h before you include atlimage.h.

Likewise, you must include atlimage.h before you include atlimpl.cpp. To accomplish this easily, include atlimage.h in your pch.h (stdafx.h in Visual Studio 2017 and earlier).

Requirements

Header: atlimage.h

`CImage::AlphaBlend`

Displays bitmaps that have transparent or semitransparent pixels.

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

Parameters

hDestDC
Handle to the destination device context.

xDest
The x-coordinate, in logical units, of the upper left corner of the destination rectangle.

yDest
The y-coordinate, in logical units, of the upper left corner of the destination rectangle.

bSrcAlpha
An alpha transparency value to be used on the entire source bitmap. The default 0xff (255) assumes that your image is opaque, and that you want to use per-pixel alpha values only.

bBlendOp
The alpha-blending function for source and destination bitmaps, a global alpha value to be applied to the entire source bitmap, and format information for the source bitmap. The source and destination blend functions are currently limited to AC_SRC_OVER.

pointDest
A reference to a POINT structure that identifies the upper left corner of the destination rectangle, in logical units.

nDestWidth
The width, in logical units, of the destination rectangle.

nDestHeight
The height, in logical units, of the destination rectangle.

xSrc
The logical x-coordinate of the upper left corner of the source rectangle.

ySrc
The logical y-coordinate of the upper left corner of the source rectangle.

nSrcWidth
The width, in logical units, of the source rectangle.

nSrcHeight
The height, in logical units, of the source rectangle.

rectDest
A reference to a RECT structure, identifying the destination.

rectSrc
A reference to a RECT structure, identifying the source.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Alpha-blend bitmaps support color blending on a per-pixel basis.

When bBlendOp is set to the default of AC_SRC_OVER, the source bitmap is placed over the destination bitmap based on the alpha values of the source pixels.

`CImage::Attach`

Attaches hBitmap to a CImage object.

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

Parameters

hBitmap
A handle to an HBITMAP.

eOrientation
Specifies the orientation of the bitmap. Can be one of the following:

DIBOR_DEFAULT The orientation of the bitmap is determined by the operating system.
DIBOR_BOTTOMUP The lines of the bitmap are in reverse order. This causes CImage::GetBits to return a pointer near the end of the bitmap buffer and CImage::GetPitch to return a negative number.
DIBOR_TOPDOWN The lines of the bitmap are in top to bottom order. This causes CImage::GetBits to return a pointer to the first byte of the bitmap buffer and CImage::GetPitch to return a positive number.

Remarks

The bitmap can be either a non-DIB section bitmap or a DIB section bitmap. See IsDIBSection for a list of methods that you can use only with DIB section bitmaps.

`CImage::BitBlt`

Copies a bitmap from the source device context to this current device context.

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

Parameters

hDestDC
The destination HDC.

xDest
The logical x-coordinate of the upper left corner of the destination rectangle.

yDest
The logical y-coordinate of the upper left corner of the destination rectangle.

dwROP
The raster operation to be performed. Raster-operation codes define exactly how to combine the bits of the source, the destination, and the pattern (as defined by the currently selected brush) to form the destination. See BitBlt in the Windows SDK for a list of other raster-operation codes and their descriptions.

pointDest
A POINT structure indicating the upper left corner of the destination rectangle.

nDestWidth
The width, in logical units, of the destination rectangle.

nDestHeight
The height, in logical units, of the destination rectangle.

xSrc
The logical x-coordinate of the upper left corner of the source rectangle.

ySrc
The logical y-coordinate of the upper left corner of the source rectangle.

rectDest
A RECT structure indicating the destination rectangle.

pointSrc
A POINT structure indicating the upper left corner of the source rectangle.

Return Value

Nonzero if successful; otherwise zero.

Remarks

For more information, see BitBlt in the Windows SDK.

`CImage::CImage`

Constructs a CImage object.

CImage() throw();

Remarks

Once you have constructed the object, call Create, Load, LoadFromResource, or Attach to attach a bitmap to the object.

Note In Visual Studio, this class keeps a count of the number of CImage objects created. Whenever the count goes to 0, the function GdiplusShutdown is automatically called to release resources used by GDI+. This ensures that any CImage objects created directly or indirectly by DLLs are always destroyed properly and that GdiplusShutdown is not called from DllMain.

Using global CImage objects in a DLL is not recommended. If you need to use a global CImage object in a DLL, call CImage::ReleaseGDIPlus to explicitly release resources used by GDI+.

`CImage::Create`

Creates a CImage bitmap and attach it to the previously constructed CImage object.

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

Parameters

nWidth
The width of the CImage bitmap, in pixels.

nHeight
The height of the CImage bitmap, in pixels. If nHeight is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If nHeight is negative, the bitmap is a top-down DIB and its origin is the upper left corner.

nBPP
The numbers of bits per pixel in the bitmap. Usually 4, 8, 16, 24, or 32. Can be 1 for monochrome bitmaps or masks.

dwFlags
Specifies if the bitmap object has an alpha channel. Can be a combination of zero or more of the following values:

createAlphaChannel Can only be used if nBPP is 32, and eCompression is BI_RGB. If specified, the created image has an alpha (transparency) value for each pixel, stored in the 4th byte of each pixel (unused in a non-alpha 32-bit image). This alpha channel is automatically used when calling CImage::AlphaBlend.

Note

In calls to CImage::Draw, images with an alpha channel are automatically alpha blended to the destination.

Return Value

Nonzero if successful; otherwise 0.

`CImage::CreateEx`

Creates a CImage bitmap and attach it to the previously constructed CImage object.

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

Parameters

nWidth
The width of the CImage bitmap, in pixels.

nBPP
The numbers of bits per pixel in the bitmap. Usually 4, 8, 16, 24, or 32. Can be 1 for monochrome bitmaps or masks.

eCompression
Specifies the type of compression for a compressed bottom-up bitmap (top-down DIBs cannot be compressed). Can be one of the following values:

BI_RGB The format is uncompressed. Specifying this value when calling CImage::CreateEx is equivalent to calling CImage::Create.
BI_BITFIELDS The format is uncompressed and the color table consists of three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16- and 32-bpp bitmaps.

pdwBitfields
Only used if eCompression is set to BI_BITFIELDS, otherwise it must be NULL. A pointer to an array of three DWORD bitmasks, specifying which bits of each pixel are used for the red, green, and blue components of the color, respectively. For information on restrictions for the bitfields, see BITMAPINFOHEADER in the Windows SDK.

dwFlags
Specifies if the bitmap object has an alpha channel. Can be a combination of zero or more of the following values:

createAlphaChannel Can only be used if nBPP is 32, and eCompression is BI_RGB. If specified, the created image has an alpha (transparency) value for each pixel, stored in the 4th byte of each pixel (unused in a non-alpha 32-bit image). This alpha channel is automatically used when calling CImage::AlphaBlend.

Note

In calls to CImage::Draw, images with an alpha channel are automatically alpha blended to the destination.

Return Value

TRUE if successful. Otherwise FALSE.

Example

The following example creates a 100x100 pixel bitmap, using 16 bits to encode each pixel. In a given 16-bit pixel, bits 0-3 encode the red component, bits 4-7 encode green, and bits 8-11 encode blue. The remaining 4 bits are unused.

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

`CImage::Destroy`

Detaches the bitmap from the CImage object and destroys the bitmap.

void Destroy() throw();

`CImage::Detach`

Detaches a bitmap from a CImage object.

HBITMAP Detach() throw();

Return Value

A handle to the bitmap detached, or NULL if no bitmap is attached.

`CImage::Draw`

Copies a bitmap from the source device context to the current device context.

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

Parameters

hDestDC
A handle to the destination device context.

xDest
The x-coordinate, in logical units, of the upper left corner of the destination rectangle.

yDest
The y-coordinate, in logical units, of the upper left corner of the destination rectangle.

nDestWidth
The width, in logical units, of the destination rectangle.

nDestHeight
The height, in logical units, of the destination rectangle.

xSrc
The x-coordinate, in logical units, of the upper left corner of the source rectangle.

ySrc
The y-coordinate, in logical units, of the upper left corner of the source rectangle.

nSrcWidth
The width, in logical units, of the source rectangle.

nSrcHeight
The height, in logical units, of the source rectangle.

rectDest
A reference to a RECT structure, identifying the destination.

rectSrc
A reference to a RECT structure, identifying the source.

pointDest
A reference to a POINT structure that identifies the upper left corner of the destination rectangle, in logical units.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Draw performs the same operation as StretchBlt, unless the image contains a transparent color or alpha channel. In that case, Draw performs the same operation as either TransparentBlt or AlphaBlend as required.

For versions of Draw that do not specify a source rectangle, the entire source image is the default. For the version of Draw that does not specify a size for the destination rectangle, the size of the source image is the default and no stretching or shrinking occurs.

`CImage::GetBits`

Retrieves a pointer to the actual bit values of a given pixel in a bitmap.

void* GetBits() throw();

Return Value

A pointer to the bitmap buffer. If the bitmap is a bottom-up DIB, the pointer points near the end of the buffer. If the bitmap is a top-down DIB, the pointer points to the first byte of the buffer.

Remarks

Using this pointer, along with the value returned by GetPitch, you can locate and change individual pixels in an image.

Note

This method supports only DIB section bitmaps; consequently, you access the pixels of a CImage object the same way you would the pixels of a DIB section. The returned pointer points to the pixel at the location (0, 0).

`CImage::GetBPP`

Retrieves the bits-per-pixel value.

int GetBPP() const throw();

Return Value

The number of bits per pixel.

Remarks

This value determines the number of bits that define each pixel and the maximum number of colors in the bitmap.

The bits per pixel is usually 1, 4, 8, 16, 24, or 32. See the biBitCount member of BITMAPINFOHEADER in the Windows SDK for more information about this value.

`CImage::GetColorTable`

Retrieves red, green, blue (RGB) color values from a range of entries in the palette of the DIB section.

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

Parameters

iFirstColor
The color table index of the first entry to retrieve.

nColors
The number of color table entries to retrieve.

prgbColors
A pointer to the array of RGBQUAD structures to retrieve the color table entries.

`CImage::GetDC`

Retrieves the device context that currently has the image selected into it.

HDC GetDC() const throw();

Return Value

A handle to a device context.

Remarks

For each call to GetDC, you must have a subsequent call to ReleaseDC.

`CImage::GetExporterFilterString`

Finds image formats available for saving images.

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

Parameters

strExporters
A reference to a CSimpleString object. See Remarks for more information.

aguidFileTypes
An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in pszAllFilesDescription below, aguidFileTypes[0] is GUID_NULL and the remaining array values are the image file formats supported by the current operating system.

Note

For a complete list of constants, see Image File Format Constants in the Windows SDK.

pszAllFilesDescription
If this parameter is not NULL, the filter string will have one additional filter at the beginning of the list. This filter will have the current value of pszAllFilesDescription for its description, and accepts files of any extension supported by any other exporter in the list.

For example:

//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
Set of bit flags specifying which file types to exclude from the list. Allowable flags are:

excludeGIF = 0x01 Excludes GIF files.
excludeBMP = 0x02 Excludes BMP (Windows Bitmap) files.
excludeEMF = 0x04 Excludes EMF (Enhanced Metafile) files.
excludeWMF = 0x08 Excludes WMF (Windows Metafile) files.
excludeJPEG = 0x10 Excludes JPEG files.
excludePNG = 0x20 Excludes PNG files.
excludeTIFF = 0x40 Excludes TIFF files.
excludeIcon = 0x80 Excludes ICO (Windows Icon) files.
excludeOther = 0x80000000 Excludes any other file type not listed above.
excludeDefaultLoad = 0 For load, all file types are included by default
excludeDefaultSave = excludeIcon | excludeEMF | excludeWMF For saving, these files are excluded by default because they usually have special requirements.

chSeparator
The separator used between the image formats. See Remarks for more information.

Return Value

A standard HRESULT.

Remarks

You can pass the resulting format string to your MFC CFileDialog object to expose the file extensions of the available image formats in the File Save As dialog box.

The parameter strExporter has the format:

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

where | is the separator character specified by chSeparator. For example:

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

Use the default separator | if you pass this string to an MFC CFileDialog object. Use the null separator '\0' if you pass this string to a common File Save dialog box.

`CImage::GetHeight`

Retrieves the height, in pixels, of an image.

int GetHeight() const throw();

Return Value

The height, in pixels, of an image.

`CImage::GetImporterFilterString`

Finds image formats available for loading images.

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

Parameters

strImporters
A reference to a CSimpleString object. See Remarks for more information.

aguidFileTypes
An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in pszAllFilesDescription below, *aguidFileTypes[0]* is GUID_NULL with the remaining array values are the image file formats supported by the current operating system.

Note

For a complete list of constants, see Image File Format Constants in the Windows SDK.

For example:

//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
Set of bit flags specifying which file types to exclude from the list. Allowable flags are:

excludeGIF = 0x01 Excludes GIF files.
excludeBMP = 0x02 Excludes BMP (Windows Bitmap) files.
excludeEMF = 0x04 Excludes EMF (Enhanced Metafile) files.
excludeWMF = 0x08 Excludes WMF (Windows Metafile) files.
excludeJPEG = 0x10 Excludes JPEG files.
excludePNG = 0x20 Excludes PNG files.
excludeTIFF = 0x40 Excludes TIFF files.
excludeIcon = 0x80 Excludes ICO (Windows Icon) files.
excludeOther = 0x80000000 Excludes any other file type not listed above.
excludeDefaultLoad = 0 For load, all file types are included by default
excludeDefaultSave = excludeIcon | excludeEMF | excludeWMF For saving, these files are excluded by default because they usually have special requirements.

chSeparator
The separator used between the image formats. See Remarks for more information.

Remarks

You can pass the resulting format string to your MFC CFileDialog object to expose the file extensions of the available image formats in the File Open dialog box.

The parameter strImporter has the format:

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

where | is the separator character specified by chSeparator. For example:

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

Use the default separator | if you pass this string to an MFC CFileDialog object. Use the null separator '\0' if you pass this string to a common File Open dialog box.

`CImage::GetMaxColorTableEntries`

Retrieves the maximum number of entries in the color table.

int GetMaxColorTableEntries() const throw();

Return Value

The number of entries in the color table.

Remarks

This method supports only DIB section bitmaps.

`CImage::GetPitch`

Retrieves the pitch of an image.

int GetPitch() const throw();

Return Value

The pitch of the image. If the return value is negative, the bitmap is a bottom-up DIB and its origin is the lower left corner. If the return value is positive, the bitmap is a top-down DIB and its origin is the upper left corner.

Remarks

The pitch is the distance, in bytes, between two memory addresses that represent the beginning of one bitmap line and the beginning of the next bitmap line. Because pitch is measured in bytes, the pitch of an image helps you to determine the pixel format. The pitch can also include additional memory, reserved for the bitmap.

Use GetPitch with GetBits to find individual pixels of an image.

Note

This method supports only DIB section bitmaps.

`CImage::GetPixel`

Retrieves the color of the pixel at the location specified by x and y.

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

Parameters

x
The x-coordinate of the pixel.

y
The y-coordinate of the pixel.

Return Value

The red, green, blue (RGB) value of the pixel. If the pixel is outside of the current clipping region, the return value is CLR_INVALID.

`CImage::GetPixelAddress`

Retrieves the exact address of a pixel.

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

Parameters

x
The x-coordinate of the pixel.

y
The y-coordinate of the pixel.

Remarks

The address is determined according to the coordinates of a pixel, the pitch of the bitmap, and the bits per pixel.

For formats that have less than 8 bits per pixel, this method returns the address of the byte containing the pixel. For example, if your image format has 4 bits per pixel, GetPixelAddress returns the address of the first pixel in the byte, and you must calculate for 2 pixels per byte.

Note

This method supports only DIB section bitmaps.

`CImage::GetTransparentColor`

Retrieves the indexed location of the transparent color in the color palette.

LONG GetTransparentColor() const throw();

Return Value

The index of the transparent color.

`CImage::GetWidth`

Retrieves the width, in pixels, of an image.

int GetWidth() const throw();

Return Value

The width of the bitmap, in pixels.

`CImage::IsDIBSection`

Determines if the attached bitmap is a DIB section.

bool IsDIBSection() const throw();

Return Value

TRUE if the attached bitmap is a DIB section. Otherwise FALSE.

Remarks

If the bitmap is not a DIB section, you cannot use the following CImage methods, which support only DIB section bitmaps:

GetBits
GetColorTable
GetMaxColorTableEntries
GetPitch
GetPixelAddress
IsIndexed
SetColorTable

`CImage::IsIndexed`

Determines whether a bitmap's pixels are mapped to a color palette.

bool IsIndexed() const throw();

Return Value

TRUE if indexed; otherwise FALSE.

Remarks

This method returns TRUE only if the bitmap is 8-bit (256 colors) or less.

Note

This method supports only DIB section bitmaps.

`CImage::IsNull`

Determines if a bitmap is currently loaded.

bool IsNull() const throw();

Remarks

This method returns TRUE if a bitmap is not currently loaded; otherwise FALSE.

`CImage::IsTransparencySupported`

Indicates whether the application supports transparent bitmaps.

static BOOL IsTransparencySupported() throw();

Return Value

Nonzero if the current platform supports transparency. Otherwise 0.

Remarks

If the return value is nonzero, and transparency is supported, a call to AlphaBlend, TransparentBlt, or Draw will handle transparent colors.

`CImage::Load`

Loads an image.

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

Parameters

pszFileName
A pointer to a string containing the name of the image file to load.

pStream
A pointer to a stream containing the name of the image file to load.

Return Value

A standard HRESULT.

Remarks

Loads the image specified by pszFileName or pStream.

Valid image types are BMP, GIF, JPEG, PNG, and TIFF.

`CImage::LoadFromResource`

Loads an image from a BITMAP resource.

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

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

Parameters

hInstance
Handle to an instance of the module that contains the image to be loaded.

pszResourceName
A pointer to the string containing the name of the resource containing the image to load.

nIDResource
The ID of the resource to load.

Remarks

The resource must be of type BITMAP.

`CImage::MaskBlt`

Combines the color data for the source and destination bitmaps using the specified mask and raster operation.

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

Parameters

hDestDC
The handle to the module whose executable contains the resource.

xDest
The x-coordinate, in logical units, of the upper left corner of the destination rectangle.

yDest
The y-coordinate, in logical units, of the upper left corner of the destination rectangle.

nDestWidth
The width, in logical units, of the destination rectangle and source bitmap.

nDestHeight
The height, in logical units, of the destination rectangle and source bitmap.

xSrc
The logical x-coordinate of the upper left corner of the source bitmap.

ySrc
The logical y-coordinate of the upper left corner of the source bitmap.

hbmMask
Handle to the monochrome mask bitmap combined with the color bitmap in the source device context.

xMask
The horizontal pixel offset for the mask bitmap specified by the hbmMask parameter.

yMask
The vertical pixel offset for the mask bitmap specified by the hbmMask parameter.

dwROP
Specifies both foreground and background ternary raster operation codes that the method uses to control the combination of source and destination data. The background raster operation code is stored in the high-order byte of the high-order word of this value; the foreground raster operation code is stored in the low-order byte of the high-order word of this value; the low-order word of this value is ignored, and should be zero. For a discussion of foreground and background in the context of this method, see MaskBlt in the Windows SDK. For a list of common raster operation codes, see BitBlt in the Windows SDK.

rectDest
A reference to a RECT structure, identifying the destination.

pointSrc
A POINT structure indicating the upper left corner of the source rectangle.

pointMask
A POINT structure indicating the upper left corner of the mask bitmap.

pointDest
A reference to a POINT structure that identifies the upper left corner of the destination rectangle, in logical units.

Return Value

Nonzero if successful, otherwise 0.

Remarks

This method applies to Windows NT, versions 4.0 and later only.

`CImage::operator HBITMAP`

Use this operator to get the attached Windows GDI handle of the CImage object. This operator is a casting operator, which supports direct use of an HBITMAP object.

`CImage::PlgBlt`

Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context.

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

Parameters

hDestDC
A handle to the destination device context.

pPoints
A pointer to an array of three points in logical space that identify three corners of the destination parallelogram. The upper left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram.

hbmMask
A handle to an optional monochrome bitmap that is used to mask the colors of the source rectangle.

xSrc
The x-coordinate, in logical units, of the upper left corner of the source rectangle.

ySrc
The y-coordinate, in logical units, of the upper left corner of the source rectangle.

nSrcWidth
The width, in logical units, of the source rectangle.

nSrcHeight
The height, in logical units, of the source rectangle.

xMask
The x-coordinate of the upper left corner of the monochrome bitmap.

yMask
The y-coordinate of the upper left corner of the monochrome bitmap.

rectSrc
A reference to a RECT structure specifying the coordinates of the source rectangle.

pointMask
A POINT structure indicating the upper left corner of the mask bitmap.

Return Value

Nonzero if successful, otherwise 0.

Remarks

If hbmMask identifies a valid monochrome bitmap, PlgBit uses this bitmap to mask the bits of color data from the source rectangle.

This method applies to Windows NT, versions 4.0 and later only. See PlgBlt in the Windows SDK for more detailed information.

`CImage::ReleaseDC`

Releases the device context.

void ReleaseDC() const throw();

Remarks

Because only one bitmap can be selected into a device context at a time, you must call ReleaseDC for each call to GetDC.

`CImage::ReleaseGDIPlus`

Releases resources used by GDI+.

void ReleaseGDIPlus() throw();

Remarks

This method must be called to free resources allocated by a global CImage object. See CImage::CImage.

`CImage::Save`

Saves an image to the specified stream or file on disk.

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

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

Parameters

pStream
A pointer to a COM IStream object containing the file image data.

pszFileName
A pointer to the file name for the image.

guidFileType
The file type to save the image as. Can be one of the following:

ImageFormatBMP An uncompressed bitmap image.
ImageFormatPNG A Portable Network Graphic (PNG) compressed image.
ImageFormatJPEG A JPEG compressed image.
ImageFormatGIF A GIF compressed image.

Note

For a complete list of constants, see Image File Format Constants in the Windows SDK.

Return Value

A standard HRESULT.

Remarks

Call this function to save the image using a specified name and type. If the guidFileType parameter is not included, the file name's file extension will be used to determine the image format. If no extension is provided, the image will be saved in BMP format.

`CImage::SetColorTable`

Sets the red, green, blue (RGB) color values for a range of entries in the palette of the DIB section.

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

Parameters

iFirstColor
The color table index of the first entry to set.

nColors
The number of color table entries to set.

prgbColors
A pointer to the array of RGBQUAD structures to set the color table entries.

Remarks

This method supports only DIB section bitmaps.

`CImage::SetPixel`

Sets the color of a pixel at a given location in the bitmap.

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

Parameters

x
The horizontal location of the pixel to set.

y
The vertical location of the pixel to set.

color
The color to which you set the pixel.

Remarks

This method fails if the pixel coordinates lie outside of the selected clipping region.

`CImage::SetPixelIndexed`

Sets the pixel color to the color located at iIndex in the color palette.

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

Parameters

x
The horizontal location of the pixel to set.

y
The vertical location of the pixel to set.

iIndex
The index of a color in the color palette.

`CImage::SetPixelRGB`

Sets the pixel at the locations specified by x and y to the colors indicated by r, g, and b, in a red, green, blue (RGB) image.

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

Parameters

x
The horizontal location of the pixel to set.

y
The vertical location of the pixel to set.

r
The intensity of the red color.

g
The intensity of the green color.

b
The intensity of the blue color.

Remarks

The red, green, and blue parameters are each represented by a number between 0 and 255. If you set all three parameters to zero, the combined resulting color is black. If you set all three parameters to 255, the combined resulting color is white.

`CImage::SetTransparentColor`

Sets a color at a given indexed location as transparent.

LONG SetTransparentColor(LONG iTransparentColor) throw();

Parameters

iTransparentColor
The index, in a color palette, of the color to set to transparent. If -1, no color is set to transparent.

Return Value

The index of the color previously set as transparent.

`CImage::StretchBlt`

Copies a bitmap from the source device context to this current device context.

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