TBitmap( unit KOL.pas ) ï TObj ï _TObj

TBitmap = object( TObj )

Bitmap incapsulation object.

TBitmap properties

property Width: Integer;
Width of bitmap. To make code smaller, avoid changing Width or Height after bitmap is created (using NewBitmap) or after it is loaded from file, stream of resource.

property Height: Integer;
Height of bitmap. To make code smaller, avoid changing Width or Height after bitmap is created (using NewBitmap) or after it is loaded from file, stream of resource.

property BoundsRect: TRect;    Ñ   
Returns rectangle (0,0,Width,Height).

property Empty: Boolean;    Ñ   
Returns True if Width or Height is 0.

property Handle: HBitmap;
Handle of bitmap. Created whenever property accessed. To check if handle is allocated (without allocating it), use HandleAllocated property.

property HandleAllocated: Boolean;    Ñ   
Returns True, if Handle already allocated.

property HandleType: TBitmapHandleType;
bmDIB, if DIB part of image data is filled and stored internally in TBitmap object. DIB image therefore can have Handle allocated, which require resources. Use HandleAllocated funtion to determine if handle is allocated and Dormant method to remove it, if You want to economy GDI resources. (Actually Handle needed for DIB bitmap only in case when Canvas is used to draw on bitmap surface). Please note also, that before saving bitmap to file or stream, it is converted to DIB.

property PixelFormat: TPixelFormat;
Current pixel format. If format of bitmap is unknown, or bitmap is DDB, value is pfDevice. Setting PixelFormat to any other format converts bitmap to DIB, back to pfDevice converts bitmap to DDB again. Avoid such conversations for large bitmaps or for numerous bitmaps in your application to keep good performance.

property Canvas: PCanvas;    Ñ   
Canvas can be used to draw onto bitmap. Whenever it is accessed, handle is allocated for bitmap, if it is not yet (to make it possible to select bitmap to display compatible device context).

property BkColor: TColor;
Used to fill background for Bitmap, when its width or height is increased. Although this value always synchronized with Canvas.Brush.Color, use it instead if You do not use Canvas for drawing on bitmap surface.

property Pixels[ X, Y: Integer ]: TColor;
Allows to obtain or change certain pixels of a bitmap. This method is both for DIB and DDB bitmaps, and leads to allocate handle anyway. For DIB bitmaps, it is possible to use property DIBPixels[ ] instead, which is much faster and does not require in Handle.

property ScanLineSize: Integer;    Ñ   
Returns size of scan line in bytes. Use it to measure size of a single ScanLine. To calculate increment value from first byte of ScanLine to first byte of next ScanLine, use difference

  Integer(ScanLine[1]-ScanLine[0])

(this is because bitmap can be oriented from bottom to top, so step can be negative).

property ScanLine[ Y: Integer ]: Pointer;    Ñ   
Use ScanLine to access DIB bitmap pixels in memory to direct access it fast. Take in attention, that for different pixel formats, different bit counts are used to represent bitmap pixels. Also do not forget, that for formats pf4bit and pf8bit, pixels actually are indices to palette entries, and for formats pf16bit, pf24bit and pf32bit are actually RGB values (for pf16bit B:5-G:6-R:5, for pf15bit B:5-G:5-R:5 (high order bit not used), for pf24bit B:8-G:8-R:8, and for pf32bit high order byte of TRGBQuad structure is not used).

property DIBPixels[ X, Y: Integer ]: TColor;
Allows direct access to pixels of DIB bitmap, faster then Pixels[ ] property. Access to read is slower for pf15bit, pf16bit formats (because some conversation needed to translate packed RGB color to TColor). And for write, operation performed most slower for pf4bit, pf8bit (searching nearest color required) and fastest for pf24bit, pf32bit and pf1bit.

property DIBPalEntryCount: Integer;    Ñ   
Returns palette entries count for DIB image. Always returns 2 for pf1bit, 16 for pf4bit, 256 for pf8bit and 0 for other pixel formats.

property DIBPalEntries[ Idx: Integer ]: TColor;
Provides direct access to DIB palette.

property DIBBits: Pointer;    Ñ   
This property is mainly for internal use.

property DIBSize: Integer;    Ñ   
Size of DIBBits array.

property DIBHeader: PBitmapInfo;    Ñ   
This property is mainly for internal use.

Properties, inherited from TObj

TBitmap methods

procedure Clear;
Makes bitmap empty, setting its Width and Height to 0.

procedure LoadFromFile( const Filename: KOLString );
Loads bitmap from file (LoadFromStream used).

function LoadFromFileEx( const Filename: KOLString ): Boolean;
Loads bitmap from a file. If necessary, bitmap is RLE-decoded. Code given by Vyacheslav A. Gavrik.

procedure SaveToFile( const Filename: KOLString );
Stores bitmap to file (SaveToStream used).

procedure LoadFromStream( Strm: PStream );
Loads bitmap from stream. Follow loading, bitmap has DIB format (without handle allocated). It is possible to draw DIB bitmap without creating handle for it, which can economy GDI resources.

function LoadFromStreamEx( Strm: PStream ): Boolean;
Loads bitmap from a stream. Difference is that RLE decoding supported. Code given by Vyacheslav A. Gavrik.

procedure SaveToStream( Strm: PStream );
Saves bitmap to stream. If bitmap is not DIB, it is converted to DIB before saving.

procedure LoadFromResourceID( Inst: DWORD; ResID: Integer );
Loads bitmap from resource using integer ID of resource. To load by name, use LoadFromResurceName. To load resource of application itself, pass hInstance as first parameter. This method also can be used to load system predefined bitmaps, if 0 is passed as Inst parameter:

OBM_BTNCORNERS OBM_REDUCE
OBM_BTSIZE       OBM_REDUCED
OBM_CHECK        OBM_RESTORE
OBM_CHECKBOXES   OBM_RESTORED
OBM_CLOSE        OBM_RGARROW
OBM_COMBO        OBM_RGARROWD
OBM_DNARROW      OBM_RGARROWI
OBM_DNARROWD     OBM_SIZE
OBM_DNARROWI     OBM_UPARROW
OBM_LFARROW      OBM_UPARROWD
OBM_LFARROWD     OBM_UPARROWI
OBM_LFARROWI     OBM_ZOOM
OBM_MNARROW      OBM_ZOOMD

procedure LoadFromResourceName( Inst: DWORD; ResName: PKOLChar );
Loads bitmap from resurce (using passed name of bitmap resource.

function Assign( SrcBmp: PBitmap ): Boolean;
Assigns bitmap from another. Returns False if not success. Note: remember, that Canvas is not assigned - only bitmap image is copied. And for DIB, handle is not allocating due this process.

function ReleaseHandle: HBitmap;
Returns Handle and releases it, so bitmap no more know about handle. This method does not destroy bitmap image, but converts it into DIB. Returned Handle actually is a handle of copy of original bitmap. If You need not in keping it up, use Dormant method instead.

procedure Dormant;
Releases handle from bitmap and destroys it. But image is not destroyed and its data are preserved in DIB format. Please note, that in KOL, DIB bitmaps can be drawn onto given device context without allocating of handle. So, it is very useful to call Dormant preparing it using Canvas drawing operations - to economy GDI resources.

function BitsPerPixel: Integer;
Returns bits per pixel if possible.

procedure Draw( DC: HDC; X, Y: Integer );
Draws bitmap to given device context. If bitmap is DIB, it is always drawing using SetDIBitsToDevice API call, which does not require bitmap handle (so, it is very sensible to call Dormant method to free correspondent GDI resources).

procedure StretchDraw( DC: HDC; const Rect: TRect );
Draws bitmap onto DC, stretching it to fit given rectangle Rect.

procedure DrawTransparent( DC: HDC; X, Y: Integer; TranspColor: TColor );
Draws bitmap onto DC transparently, using TranspColor as transparent. See function DesktopPixelFormat also.

procedure StretchDrawTransparent( DC: HDC; const Rect: TRect; TranspColor: TColor );
Draws bitmap onto given rectangle of destination DC (with stretching it to fit Rect) - transparently, using TranspColor as transparent. See function DesktopPixelFormat also.

procedure DrawMasked( DC: HDC; X, Y: Integer; Mask: HBitmap );
Draws bitmap to destination DC transparently by mask. It is possible to pass as a mask handle of another TBitmap, previously converted to monochrome mask using Convert2Mask method.

procedure StretchDrawMasked( DC: HDC; const Rect: TRect; Mask: HBitmap );
Like DrawMasked, but with stretching image onto given rectangle.

procedure Convert2Mask( TranspColor: TColor );
Converts bitmap to monochrome (mask) bitmap with TranspColor replaced to clBlack and all other ones to clWhite. Such mask bitmap can be used to draw original bitmap transparently, with given TranspColor as transparent. (To preserve original bitmap, create new instance of TBitmap and assign original bitmap to it). See also DrawTransparent and StretchDrawTransparent methods.

procedure Invert;
Obvious.

procedure RemoveCanvas;
Call this method to destroy Canvas and free GDI resources.

function DIBPalNearestEntry( Color: TColor ): Integer;
Returns index of entry in DIB palette with color nearest (or matching) to given one.

procedure DIBDrawRect( DC: HDC; X, Y: Integer; const R: TRect );
This procedure copies given rectangle to the target device context, but only for DIB bitmap (using SetDIBBitsToDevice API call).

procedure RotateRight;
Rotates bitmap right (90 degree). Bitmap must be DIB. If You definitevely know format of a bitmap, use instead one of methods RotateRightMono, RotateRight4bit, RotateRight8bit, RotateRight16bit or RotateRightTrueColor - this will economy code. But if for most of formats such methods are called, this can be more economy just to call always universal method RotateRight.

procedure RotateLeft;
Rotates bitmap left (90 degree). Bitmap must be DIB. If You definitevely know format of a bitmap, use instead one of methods RotateLeftMono, RotateLeft4bit, RotateLeft8bit, RotateLeft16bit or RotateLeftTrueColor - this will economy code. But if for most of formats such methods are called, this can be more economy just to call always universal method RotateLeft.

procedure RotateRightMono;
Rotates bitmat right, but only if bitmap is monochrome (pf1bit).

procedure RotateLeftMono;
Rotates bitmap left, but only if bitmap is monochrome (pf1bit).

procedure RotateRight4bit;
Rotates bitmap right, but only if PixelFormat is pf4bit.

procedure RotateLeft4bit;
Rotates bitmap left, but only if PixelFormat is pf4bit.

procedure RotateRight8bit;
Rotates bitmap right, but only if PixelFormat is pf8bit.

procedure RotateLeft8bit;
Rotates bitmap left, but only if PixelFormat is pf8bit.

procedure RotateRight16bit;
Rotates bitmap right, but only if PixelFormat is pf16bit.

procedure RotateLeft16bit;
Rotates bitmap left, but only if PixelFormat is pf16bit.

procedure RotateRightTrueColor;
Rotates bitmap right, but only if PixelFormat is pf24bit or pf32bit.

procedure RotateLeftTrueColor;
Rotates bitmap left, but only if PixelFormat is pf24bit or pf32bit.

procedure FlipVertical;
Flips bitmap vertically

procedure FlipHorizontal;
Flips bitmap horizontally

procedure CopyRect( const DstRect: TRect; SrcBmp: PBitmap; const SrcRect: TRect );
It is possible to use Canvas.CopyRect for such purpose, but if You do not want use TCanvas, it is possible to copy rectangle from one bitmap to another using this function.

function CopyToClipboard: Boolean;
Copies bitmap to clipboard.

function PasteFromClipboard: Boolean;
Takes CF_DIB format bitmap from clipboard and assigns it to the TBitmap object.

Methods, inherited from TObj

TBitmap events

Events, inherited from TObj

TBitmap fields

Fields, inherited from TObj


Index ]

This help is generated 14-Jun-2010 by KOL Help generator, (C) 2000-2001 by Vladimir Kladov
Modified (C) 2003 by Alexander Bartov