CImage Class

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.

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 and was compiled for Windows 2000 or later.
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

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.

Example

// 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.

Note

The following CImage methods have limitations on their use:

Method	Limitation
PlgBlt	Works with only Windows NT 4.0 or later. Will not work on applications running on Windows 95/98 or later.
MaskBlt	Works with only Windows NT 4.0 or later. Will not work on applications running on Windows 95/98 or later.
AlphaBlend	Works with only Windows 2000, Windows 98, and later systems.
TransparentBlt	Works with only Windows 2000, Windows 98, and later systems.
Draw	Supports transparency with only Windows 2000, Windows 98, and later systems.

See CImage Limitations with Earlier Operating Systems for more detailed information about the limitations on these methods.

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 stdafx.h.

Requirements

Header: atlimage.h

See Also

Reference

Device-Independent Bitmaps

CreateDIBSection

Concepts

MMXSwarm Sample

SimpleImage Sample

Other Resources

ATL COM Desktop Components