CBitmap Class
Encapsulates a Windows graphics device interface (GDI) bitmap and provides member functions to manipulate the bitmap.
Syntax
class CBitmap : public CGdiObject
Members
Public Constructors
| Name | Description |
|---|---|
CBitmap::CBitmap |
Constructs a CBitmap object. |
Public Methods
| Name | Description |
|---|---|
CBitmap::CreateBitmap |
Initializes the object with a device-dependent memory bitmap that has a specified width, height, and bit pattern. |
CBitmap::CreateBitmapIndirect |
Initializes the object with a bitmap with the width, height, and bit pattern (if one is specified) given in a BITMAP structure. |
CBitmap::CreateCompatibleBitmap |
Initializes the object with a bitmap so that it is compatible with a specified device. |
CBitmap::CreateDiscardableBitmap |
Initializes the object with a discardable bitmap that is compatible with a specified device. |
CBitmap::FromHandle |
Returns a pointer to a CBitmap object when given a handle to a Windows HBITMAP bitmap. |
CBitmap::GetBitmap |
Fills a BITMAP structure with information about the bitmap. |
CBitmap::GetBitmapBits |
Copies the bits of the specified bitmap into the specified buffer. |
CBitmap::GetBitmapDimension |
Returns the width and height of the bitmap. The height and width are assumed to have been set previously by the SetBitmapDimension member function. |
CBitmap::LoadBitmap |
Initializes the object by loading a named bitmap resource from the application's executable file and attaching the bitmap to the object. |
CBitmap::LoadMappedBitmap |
Loads a bitmap and maps colors to current system colors. |
CBitmap::LoadOEMBitmap |
Initializes the object by loading a predefined Windows bitmap and attaching the bitmap to the object. |
CBitmap::SetBitmapBits |
Sets the bits of a bitmap to the specified bit values. |
CBitmap::SetBitmapDimension |
Assigns a width and height to a bitmap in 0.1-millimeter units. |
Public Operators
| Name | Description |
|---|---|
CBitmap::operator HBITMAP |
Returns the Windows handle attached to the CBitmap object. |
Remarks
To use a CBitmap object, construct the object, attach a bitmap handle to it with one of the initialization member functions, and then call the object's member functions.
For more information on using graphic objects like CBitmap, see Graphic Objects.
Inheritance Hierarchy
CBitmap
Requirements
Header: afxwin.h
CBitmap::CBitmap
Constructs a CBitmap object.
CBitmap();
Remarks
The resulting object must be initialized with one of the initialization member functions.
CBitmap::CreateBitmap
Initializes a device-dependent memory bitmap that has the specified width, height, and bit pattern.
BOOL CreateBitmap(
int nWidth,
int nHeight,
UINT nPlanes,
UINT nBitcount,
const void* lpBits);
Parameters
nWidth
Specifies the width (in pixels) of the bitmap.
nHeight
Specifies the height (in pixels) of the bitmap.
nPlanes
Specifies the number of color planes in the bitmap.
nBitcount
Specifies the number of color bits per display pixel.
lpBits
Points to an array of bytes that contains the initial bitmap bit values. If it is NULL, the new bitmap is left uninitialized.
Return Value
Nonzero if successful; otherwise 0.
Remarks
For a color bitmap, either the nPlanes or nBitcount parameter should be set to 1. If both of these parameters are set to 1, CreateBitmap creates a monochrome bitmap.
Although a bitmap cannot be directly selected for a display device, it can be selected as the current bitmap for a "memory device context" by using CDC::SelectObject and copied to any compatible device context by using the CDC::BitBlt function.
When you finish with the CBitmap object created by the CreateBitmap function, first select the bitmap out of the device context, then delete the CBitmap object.
For more information, see the description of the bmBits field in the BITMAP structure. The BITMAP structure is described under the CBitmap::CreateBitmapIndirect member function.
CBitmap::CreateBitmapIndirect
Initializes a bitmap that has the width, height, and bit pattern (if one is specified) given in the structure pointed to by lpBitmap.
BOOL CreateBitmapIndirect(LPBITMAP lpBitmap);
Parameters
lpBitmap
Points to a BITMAP structure that contains information about the bitmap.
Return Value
Nonzero if successful; otherwise 0.
Remarks
Although a bitmap cannot be directly selected for a display device, it can be selected as the current bitmap for a memory device context by using CDC::SelectObject and copied to any compatible device context by using the CDC::BitBlt or CDC::StretchBlt function. (The CDC::PatBlt function can copy the bitmap for the current brush directly to the display device context.)
If the BITMAP structure pointed to by the lpBitmap parameter has been filled in by using the GetObject function, the bits of the bitmap are not specified and the bitmap is uninitialized. To initialize the bitmap, an application can use a function such as CDC::BitBlt or SetDIBits to copy the bits from the bitmap identified by the first parameter of CGdiObject::GetObject to the bitmap created by CreateBitmapIndirect.
When you finish with the CBitmap object created with CreateBitmapIndirect function, first select the bitmap out of the device context, then delete the CBitmap object.
CBitmap::CreateCompatibleBitmap
Initializes a bitmap that is compatible with the device specified by pDC.
BOOL CreateCompatibleBitmap(
CDC* pDC,
int nWidth,
int nHeight);
Parameters
pDC
Specifies the device context.
nWidth
Specifies the width (in pixels) of the bitmap.
nHeight
Specifies the height (in pixels) of the bitmap.
Return Value
Nonzero if successful; otherwise 0.
Remarks
The bitmap has the same number of color planes or the same bits-per-pixel format as the specified device context. It can be selected as the current bitmap for any memory device that is compatible with the one specified by pDC.
If pDC is a memory device context, the bitmap returned has the same format as the currently selected bitmap in that device context. A "memory device context" is a block of memory that represents a display surface. It can be used to prepare images in memory before copying them to the actual display surface of the compatible device.
When a memory device context is created, GDI automatically selects a monochrome stock bitmap for it.
Since a color memory device context can have either color or monochrome bitmaps selected, the format of the bitmap returned by the CreateCompatibleBitmap function is not always the same; however, the format of a compatible bitmap for a nonmemory device context is always in the format of the device.
When you finish with the CBitmap object created with the CreateCompatibleBitmap function, first select the bitmap out of the device context, then delete the CBitmap object.
CBitmap::CreateDiscardableBitmap
Initializes a discardable bitmap that is compatible with the device context identified by pDC.
BOOL CreateDiscardableBitmap(
CDC* pDC,
int nWidth,
int nHeight);
Parameters
pDC
Specifies a device context.
nWidth
Specifies the width (in bits) of the bitmap.
nHeight
Specifies the height (in bits) of the bitmap.
Return Value
Nonzero if successful; otherwise 0.
Remarks
The bitmap has the same number of color planes or the same bits-per-pixel format as the specified device context. An application can select this bitmap as the current bitmap for a memory device that is compatible with the one specified by pDC.
Windows can discard a bitmap created by this function only if an application has not selected it into a display context. If Windows discards the bitmap when it is not selected and the application later attempts to select it, the CDC::SelectObject function will return NULL.
When you finish with the CBitmap object created with the CreateDiscardableBitmap function, first select the bitmap out of the device context, then delete the CBitmap object.
CBitmap::FromHandle
Returns a pointer to a CBitmap object when given a handle to a Windows GDI bitmap.
static CBitmap* PASCAL FromHandle(HBITMAP hBitmap);
Parameters
hBitmap
Specifies a Windows GDI bitmap.
Return Value
A pointer to a CBitmap object if successful; otherwise NULL.
Remarks
If a CBitmap object is not already attached to the handle, a temporary CBitmap object is created and attached. This temporary CBitmap object is valid only until the next time the application has idle time in its event loop, at which time all temporary graphic objects are deleted. Another way of saying this is that the temporary object is only valid during the processing of one window message.
CBitmap::GetBitmap
Retrieves image properties for the attached bitmap.
int GetBitmap(BITMAP* pBitMap);
Parameters
pBitMap
Pointer to a BITMAP structure that will receive the image properties. This parameter must not be NULL.
Return Value
Nonzero if the method was successful; otherwise 0.
Remarks
CBitmap::GetBitmapBits
Copies the bit pattern of the attached bitmap into the specified buffer.
DWORD GetBitmapBits(
DWORD dwCount,
LPVOID lpBits) const;
Parameters
dwCount
The number of bytes to copy to the buffer.
lpBits
Pointer to the buffer that will receive the bitmap.
Return Value
The number of bytes copied to the buffer if the method was successful; otherwise 0.
Remarks
Use CBitmap::GetBitmap to determine the required buffer size.
CBitmap::GetBitmapDimension
Returns the width and height of the bitmap.
CSize GetBitmapDimension() const;
Return Value
The width and height of the bitmap, measured in 0.1-millimeter units. The height is in the cy member of the CSize object, and the width is in the cx member. If the bitmap width and height have not been set by using SetBitmapDimension, the return value is 0.
Remarks
The height and width are assumed to have been set previously by using the SetBitmapDimension member function.
CBitmap::LoadBitmap
Loads the bitmap resource named by lpszResourceName or identified by the ID number in nIDResource from the application's executable file.
BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);
Parameters
lpszResourceName
Points to a null-terminated string that contains the name of the bitmap resource.
nIDResource
Specifies the resource ID number of the bitmap resource.
Return Value
Nonzero if successful; otherwise 0.
Remarks
The loaded bitmap is attached to the CBitmap object.
If the bitmap identified by lpszResourceName does not exist or if there is insufficient memory to load the bitmap, the function returns 0.
You can use the CGdiObject::DeleteObject function to delete bitmap loaded by the LoadBitmap function, or the CBitmap destructor will delete the object for you.
Caution
Before you delete the object, make sure it is not selected into a device context.
The following bitmaps were added to Windows versions 3.1 and later:
OBM_UPARRROWIOBM_DNARROWIOBM_RGARROWIOBM_LFARROWI
These bitmaps are not found in device drivers for Windows versions 3.0 and earlier. For a complete list of bitmaps and a display of their appearance, see the Windows SDK.
CBitmap::LoadMappedBitmap
Call this member function to load a bitmap and map the colors to the current system colors.
BOOL LoadMappedBitmap(
UINT nIDBitmap,
UINT nFlags = 0,
LPCOLORMAP lpColorMap = NULL,
int nMapSize = 0);
Parameters
nIDBitmap
The ID of the bitmap resource.
nFlags
A flag for a bitmap. Can be zero or CMB_MASKED.
lpColorMap
A pointer to a COLORMAP structure that contains the color information needed to map the bitmaps. If this parameter is NULL, the function uses the default color map.
nMapSize
The number of color maps pointed to by lpColorMap.
Return Value
Nonzero if successful; otherwise 0.
Remarks
By default, LoadMappedBitmap will map colors commonly used in button glyphs.
For information about creating a mapped bitmap, see the Windows function CreateMappedBitmap and the COLORMAP structure in the Windows SDK.
CBitmap::LoadOEMBitmap
Loads a predefined bitmap used by Windows.
BOOL LoadOEMBitmap(UINT nIDBitmap);
Parameters
nIDBitmap
ID number of the predefined Windows bitmap. The possible values are listed below from WINDOWS.H:
OBM_BTNCORNERS
OBM_BTSIZE
OBM_CHECK
OBM_CHECKBOXES
OBM_CLOSE
OBM_COMBO
OBM_DNARROW
OBM_DNARROWD
OBM_DNARROWI
OBM_LFARROW
OBM_LFARROWD
OBM_LFARROWI
OBM_MNARROW
OBM_OLD_CLOSE
OBM_OLD_DNARROW
OBM_OLD_LFARROW
OBM_OLD_REDUCE
OBM_OLD_RESTORE
OBM_OLD_RGARROW
OBM_OLD_UPARROW
OBM_OLD_ZOOM
OBM_REDUCE
OBM_REDUCED
OBM_RESTORE
OBM_RESTORED
OBM_RGARROW
OBM_RGARROWD
OBM_RGARROWI
OBM_SIZE
OBM_UPARROW
OBM_UPARROW
OBM_UPARROWD
OBM_ZOOM
OBM_ZOOMD
Return Value
Nonzero if successful; otherwise 0.
Remarks
Bitmap names that begin with OBM_OLD represent bitmaps used by Windows versions prior to 3.0.
Note that the constant OEMRESOURCE must be defined before including WINDOWS.H in order to use any of the OBM_ constants.
CBitmap::operator HBITMAP
Use this operator to get the attached Windows GDI handle of the CBitmap object.
operator HBITMAP() const;
Return Value
If successful, a handle to the Windows GDI object represented by the CBitmap object; otherwise NULL.
Remarks
This operator is a casting operator, which supports direct use of an HBITMAP object.
For more information about using graphic objects, see Graphic Objects in the Windows SDK.
CBitmap::SetBitmapBits
Sets the bits of a bitmap to the bit values given by lpBits.
DWORD SetBitmapBits(
DWORD dwCount,
const void* lpBits);
Parameters
dwCount
Specifies the number of bytes pointed to by lpBits.
lpBits
Points to the BYTE array that contains the pixel values to be copied to the CBitmap object. In order for the bitmap to be able to render its image correctly, the values should be formatted to conform to the height, width and color depth values that were specified when the CBitmap instance was created. For more information, see CBitmap::CreateBitmap.
Return Value
The number of bytes used in setting the bitmap bits; 0 if the function fails.
CBitmap::SetBitmapDimension
Assigns a width and height to a bitmap in 0.1-millimeter units.
CSize SetBitmapDimension(
int nWidth,
int nHeight);
Parameters
nWidth
Specifies the width of the bitmap (in 0.1-millimeter units).
nHeight
Specifies the height of the bitmap (in 0.1-millimeter units).
Return Value
The previous bitmap dimensions. Height is in the cy member variable of the CSize object, and width is in the cx member variable.
Remarks
The GDI does not use these values except to return them when an application calls the GetBitmapDimension member function.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for