BITMAP Object +
Updated: Sep 6, 2007

The Bitmap Object is a non-visible component used to prepare an image which may
be copied to visible windows.  Since a Bitmap may be loaded, drawn and modified
off-screen, it may provide more efficient animation effects.

HotDraw shows drawing a bitmap animation.  hotbmp.bas in HotToys also shows
bitmap usage.

Please note that after BITMAPINFOHEADER items -- Width, Height, Planes,
BitCount, Compression, SizeImage, XPelsPerMeter, YPelsPerMeter, ClrUsed and
ClrImportant -- are altered, the .Recreate method should be used to initialize
the BITMAP object to the new values.


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
BitCount   Number of color bits; default = 16

BMP        Handle of .bmp resource (a string) or a hBitmap (dword).

  $resource bmp1 as "MyPicture.bmp"
  MyBitmap.BMP = "bmp1"  'or hBitmap imports a bitmap into the object.

  BITMAPINFOHEADER items and .Pointer are cleared after write to .BMP.

ClrImportant Number of "important" color indeces; default = 0 (all)

ClrUsed    Number of color table indices actually used; default = 0

Compression Type of compression for a compressed bottom-up bitmap

Font

Height     Height of bitmap; default = 64

Mode       Drawing mode used when bitmap is used in Form .Draw
           Default = &HCC0020 (SRCCOPY)

  $DEFINE NOTSRCCOPY  &H330008
  $DEFINE NOTSRCERASE &H1100A6
  $DEFINE SRCCOPY     &HCC0020
  $DEFINE SRCPAINT    &HEE0086
  $DEFINE SRCAND      &H8800C6
  $DEFINE SRCINVERT   &H660046
  $DEFINE SRCERASE    &H440328
  $DEFINE MERGECOPY   &HC000CA
  $DEFINE MERGEPAINT  &HBB0226
  $DEFINE PATCOPY     &HF00021
  $DEFINE PATPAINT    &HFB0A09
  $DEFINE PATINVERT   &H5A0049
  $DEFINE DSTINVERT   &H550009
  $DEFINE BLACKNESS   &H000042
  $DEFINE WHITENESS   &HFF0062

Pixel      Gets or Draws pixel; same as Pset

           MyBMP.Pixel(x,y) = rgb_color  'set x, y pixel

           rgb_color = MyBMP.Pixel(x,y)  'get pixel at x, y

Planes     Number of bitmap planes; default = 1

SizeImage  Bitmap size in bytes

Width      Width of bitmap; default = 64

X          Left offset used in Form object .Draw method
           Default = 0

XPelsPerMeter Target device horizontal resolution in pixels per meter

Xsize      Horizontal size (width drawn) used in Form object .Draw method
           Default = 64 or .Width after .LoadFromFile or load with .BMP

Y          Top offset used in Form object .Draw method
           Default = 0

YPelsPerMeter  Target device vertical resolution in pixels per meter

Ysize      Vertical size (height drawn) used in Form object .Draw method
           Default = 64 or .Height after .LoadFromFile or load with .BMP

  Note: Changing .X and .Y affects the upper-left corner of the image drawn
  with .Draw and .Xsize and .Ysize may be less than .Width and .Height 
  respectively, to .Draw an image smaller than the full size of the bitmap.
  For example, if .Draw is repeated after .X is changed, the left edge of the
  drawn image will change.  


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
DC         Alias for .Handle which is a device context

Handle     Handle of bitmap object (not the handle of a bitmap)

Pointer    Pointer to bitmap data.  Cleared after .BMP = and .LoadFromFile.
           That is, .Pointer is valid only for user-created bitmaps.

TextHeight Height in pixels of text string argument.

           MyHeight = MyBmp.TextHeight(MyString$)

TextWidth  Width in pixels of text string argument.

           MyWidth = MyBmp.TextWidth(MyString$)


Drawing methods to Bitmap objects do not require .BeginPaint/.EndPaint nor
.GetDC/.ReleaseDC and indeed, should not be used within these device context
code blocks.  Internally, a Bitmap object *is* a device context.

Likewise, BITMAP drawing is not done in a FORM object .OnPaint routine, to
avoid changing the drawing device context value.

METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
Circle     Draws circle of radius r centered at x, y with specified color.

           MyBitmap.Circle x, y, r, rgb_color

Clear      Clears current bitmap.  MyBitmap.Clear

CopyRect   Copies source RECT (r1) of a BITMAP object (bmp1) to a destination
           RECT (r2).  bmp2.CopyRect(r2,bmp1,r1)

           Source BITMAP bmp1 may be the same as bmp1.  If image dimensions
           defined by RECT r1 <> RECT r2, then the copied image should be
           stretched or compressed to "fit" r2.  How .CopyRect copies the
           bitmap data is determined by source BITMAP bmp1.Mode.

Draw       Draws BITMAP object at x, y position

           MyBitMap.Draw 10,10,MyBitmap2  'draw at MyBitMap position 10, 10  

           The drawn rectangle of MyBitmap2 is determined by its properties. 

Ellipse    Draws ellipse (or circle) with the specified color.

           MyBitmap.Ellipse x1, y1, x2, y2, rgb_color

FillCircle Draws circle of radius r centered at x, y filled with color.

           MyBitmap.FillCircle x, y, r, rgb_color

FillEllipse 
           Draws ellipse (or circle) filled with the specified color.

           MyBitmap.FillEllipse x1, y1, x2, y2, rgb_color

FillRect   Draws rectangle (or square) filled with the specified color.

           MyBitmap.FillRect x1, y1, x2, y2, rgb_color

Font       Set font for text.  MyBitmap.Font = MyFont

Line       Draws line from x1, y1 to x2, y2 with rgb color.

           MyBitmap.Line x1, y1, x2, y2, rgb_color

LoadFromFile
           Loads .bmp file; MyBitmap.LoadFromFile "hotpic.bmp"

           BITMAPINFOHEADER items and .Pointer are cleared after .LoadFromFile.

Paint      Fills region with rgb_border color containing x, y with rgb_fill.

           MyBitmap.Paint x, y, rgb_fill, rgb_border 

Pset       Draws pixel at x, y with color.  MyBitmap.Pset(x,y)=rgb_color

Recreate   After a change in properties -- .BitCount, .Height, .Planes or
           .Width -- .Recreate is required to create a new bitmap.

           MyBmp.Width = 160: MyBmp.Height = 240: MyBmp.Recreate

Rectangle  Draws rectangle (or square) with the specified color.

           MyBitmap.Rectangle x1, y1, x2, y2, rgb_color

TextOut    Draws text string at x, y with text and background colors.

           MyBitmap.TextOut x, y, "HotBasic Artist", text_color, bk_color


###########
Please see sample code in th HotThing and HotToys downloads for tutorials on
BITMAP coding.  Drawing methods are also shown in the HotDraw download.

+ PentHouse (registered) version

Copyright 2004-2005 James J Keene PhD
Original Publication: March 2, 2004
