Win32Forth

gdiBitmap -- GDI Bitmap class.

Version 1.0

This GDI class library was written and placed in the Public Domain in 2005 by Dirk Busch

Glossary

:class gdiBitmap <super gdiObject

Bitmap class

:M CreateBitmap: ( Width Height Planes BitsPerPel pBits -- f )

The CreateBitmap function creates a bitmap with the specified width, height, and color format (color planes and bits-per-pixel).

Width  Specifies the bitmap width, in pixels.      
Height Specifies the bitmap height, in pixels.     
Planes Specifies the number of color planes used by the device.    
BitsPerPel Specifies the number of bits required to identify the color of a single pixel.
pBits Pointer to an array of color data used to set the colors in a rectangle of pixels. Each scan line in the rectangle must be word aligned (scan lines that are not word aligned must be padded with zeros). If this parameter is NULL, the contents of the new bitmap is undefined.

After a bitmap is created, it can be selected into a device context by calling the SelectObject function. The CreateBitmap function can be used to create color bitmaps. However, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmap is selected into a device context, the system must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are faster than with a color bitmap returned from CreateBitmap.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

If an application sets the nWidth or nHeight parameters to zero, CreateBitmap returns the handle to a 1-by-1 pixel, monochrome bitmap.

When you no longer need the bitmap, call the Destroy: method to delete it.

Windows 95/98: The created bitmap cannot exceed 16MB in size

:M CreateBitmapIndirect: ( pBitmap -- f )

The CreateBitmapIndirect function creates a bitmap with the specified width, height, and color format (color planes and bits-per-pixel). pBitmap Pointer to a BITMAP structure that contains information about the bitmap. If an application sets the bmWidth or bmHeight members to zero, CreateBitmapIndirect returns the handle to a 1-by-1 pixel, monochrome bitmap.

:M CreateCompatibleBitmap: ( Width Height hDC -- f )

The CreateCompatibleBitmap function creates a bitmap compatible with the device that is associated with the specified device context.

The color format of the bitmap created by the CreateCompatibleBitmap function matches the color format of the device identified by the hdc parameter. This bitmap can be selected into any memory device context that is compatible with the original device.

Because memory device contexts allow both color and monochrome bitmaps, the format of the bitmap returned by the CreateCompatibleBitmap function differs when the specified device context is a memory device context. However, a compatible bitmap that was created for a nonmemory device context always possesses the same color format and uses the same color palette as the specified device context.

Note: When a memory device context is created, it initially has a 1-by-1 monochrome bitmap selected into it. If this memory device context is used in CreateCompatibleBitmap, the bitmap that is created is a monochrome bitmap. To create a color bitmap, use the hDC that was used to create the memory device context, as shown in the following code:

    HDC memDC = CreateCompatibleDC ( hDC );
    HBITMAP memBM = CreateCompatibleBitmap ( hDC );
    SelectObject ( memDC, memBM );

If an application sets the nWidth or nHeight parameters to zero, CreateCompatibleBitmap returns the handle to a 1-by-1 pixel, monochrome bitmap.

If a DIB section, which is a bitmap created by the CreateDIBSection function, is selected into the device context identified by the hdc parameter, CreateCompatibleBitmap creates a DIB section.

When you no longer need the bitmap, call the DeleteObject function to delete it.

Windows 95/98: The created bitmap cannot exceed 16MB in size.

:M CreateDIBitmap: ( pbmih fdwInit pbInit pbmi fuUsage hdc -- f )

The CreateDIBitmap function creates a device-dependent bitmap (DDB) from a DIB and, optionally, sets the bitmap bits.
lpbmih Pointer to a bitmap information header structure, which may be one of those shown in the following table.

If fdwInit is CBM_INIT, the function uses the bitmap information header structure to obtain the desired width and height of the bitmap as well as other information. Note that a positive value for the height indicates a bottom-up DIB while a negative value for the height indicates a top-down DIB. Calling CreateDIBitmap with fdwInit as CBM_INIT is equivalent to calling the CreateCompatibleBitmap function to create a DDB in the format of the device and then calling the SetDIBits function to translate the DIB bits to the DDB.
fdwInit Specifies how the system initializes the bitmap bits. The following values is defined. Value Meaning CBM_INIT If this flag is set, the system uses the data pointed to by the lpbInit and lpbmi parameters to initialize the bitmap's bits. If this flag is clear, the data pointed to by those parameters is not used.
If fdwInit is zero, the system does not initialize the bitmap's bits.
lpbInit Pointer to an array of bytes containing the initial bitmap data. The format of the data depends on the biBitCount member of the BITMAPINFO structure to which the lpbmi parameter points.
lpbmi Pointer to a BITMAPINFO structure that describes the dimensions and color format of the array pointed to by the lpbInit parameter.
fuUsage Specifies whether the bmiColors member of the BITMAPINFO structure was initialized and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or palette indexes. The fuUsage parameter must be one of the following values.

:M CreateDIBSection: ( pbmi iUsage ppvBits hSection dwOffset hdc -- f )

The CreateDIBSection function creates a DIB that applications can write to directly. The function gives you a pointer to the location of the bitmap's bit values. You can supply a handle to a file-mapping object that the function will use to create the bitmap, or you can let the system allocate the memory for the bitmap.
hdc Handle to a device context. If the value of iUsage is DIB_PAL_COLORS, the function uses this device context's logical palette to initialize the DIB's colors.
pbmi Pointer to a BITMAPINFO structure that specifies various attributes of the DIB, including the bitmap's dimensions and colors.
iUsage Specifies the type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi (either logical palette indexes or literal RGB values). The following values are defined.

ppvBits Pointer to a variable that receives a pointer to the location of the DIB's bit values.
hSection Handle to a file-mapping object that the function will use to create the DIB. This parameter can be NULL. If hSection is not NULL, it must be a handle to a file-mapping object created by calling the CreateFileMapping function with the PAGE_READWRITE or PAGE_WRITECOPY flag. Read-only DIB sections are not supported. Handles created by other means will cause CreateDIBSection to fail. If hSection is not NULL, the CreateDIBSection function locates the bitmap's bit values at offset dwOffset in the file-mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection. If hSection is NULL, the system allocates memory for the DIB. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory. The dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL.
dwOffset Specifies the offset from the beginning of the file-mapping object referenced by hSection where storage for the bitmap's bit values is to begin. This value is ignored if hSection is NULL. The bitmap's bit values are aligned on doubleword boundaries, so dwOffset must be a multiple of the size of a DWORD.

:M SetBitmapDimension: ( width height -- oldwidth oldheight )

The SetBitmapDimension function assigns preferred dimensions to a bitmap. These dimensions can be used by applications; however, they are not used by the system.
Width Specifies the width, in 0.1-millimeter units, of the bitmap.
Height Specifies the height, in 0.1-millimeter units, of the bitmap.
An application can retrieve the dimensions assigned to a bitmap with the SetBitmapDimensionEx function by calling the GetBitmapDimension function.
The bitmap identified by hBitmap cannot be a DIB section, which is a bitmap created by the CreateDIBSection function. If the bitmap is a DIB section, the SetBitmapDimension function fails.

:M GetBitmapDimension: ( -- width height )

The GetBitmapDimension function retrieves the dimensions of a bitmap. The retrieved dimensions must have been set by the SetBitmapDimension function. The function returns the height and width of the bitmap, in .01-mm units.

:M SetDIBits:   ;M

not implemented, yet.

:M GetDIBits:   ;M

not implemented, yet.

:M LoadBitmap:  ;M

not implemented, yet.

:M MaskBlt:     ;M

not implemented, yet.

:M PlgBlt:      ;M

not implemented, yet.

;class

End of Bitmap class

Document $Id: gdiBitmap.htm,v 1.12 2007/05/26 10:24:12 dbu_de Exp $