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.

CImage image;
// Code to load/create image goes here

// Get a CDC for the image
CDC* pDC = CDC::FromHandle(image.GetDC());

// Use pDC here

image.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*.

CMyWnd::OnRButtonDown(int nFlags, CPoint mouse)
{
   CMenu menu;
   CImage image;

   // Code to create menu and load/create image goes here

   CBitmap* pBitmap = CBitmap::FromHandle(image.m_hBitmap);
   menu.AppendMenu(0, ID_SOMECOMMAND, pBitmap)
   menu.TrackPopupMenu(TPM_RIGHTBUTTON | TPM_LEFTALIGN, mouse.x, mouse.y, this);
}

For more examples, see the HttpClient Sample and the ShowImage Sample.

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:

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.

Header: atlimage.h

This class is not supported in Smart Device projects.

Tasks

Reference

Other Resources