共用方式為


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:

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