TBitmap( unit KOL.pas ) TObj _TObj

TBitmap = object( TObj )

Bitmap incapsulation object.

 

type PCanvas = ^ TCanvas;

 

type TPixelFormat =( pfDevice, pf1bit, pf4bit, pf8bit, pf15bit, pf16bit, pf24bit, pf32bit, pfCustom );

Available pixel formats.

 

type TBitmapHandleType =( bmDIB, bmDDB );

Available bitmap handle types.

 

function DesktopPixelFormat: TPixelFormat;

Returns the pixel format correspondent to current desktop color resolution. Use this function to decide which format to use for converting bitmap, planned to draw transparently using TBitmap.DrawTransparent or TBitmap.StretchDrawTransparent methods.

 

function NewBitmap( W, H: Integer ): PBitmap;

Creates bitmap object of given size. If it is possible, do not change its size (Width and Heigth) later - this can economy code a bit. See TBitmap.

 

function NewDIBBitmap( W, H: Integer; PixelFormat: TPixelFormat ): PBitmap;

Creates DIB bitmap object of given size and pixel format. If it is possible, do not change its size (Width and Heigth) later - this can economy code a bit. See TBitmap.

 

 

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;  

 

 

 

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 CoreSaveToFile( const Filename: KOLString );

Stores bitmap to file (CoreSaveToStream used).

 

procedure RLESaveToFile( const Filename: KOLString );

Stores bitmap to file (CoreSaveToStream 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 CoreSaveToStream( Strm: PStream );

Saves bitmap to stream using CORE format with RGBTRIPLE palette and with BITMAPCOREHEADER as a header. If bitmap is not DIB, it is converted to DIB before saving.

 

procedure RLESaveToStream( Strm: PStream );

Saves bitmap to stream using CORE format with RGBTRIPLE palette and with BITMAPCOREHEADER as a header. 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:

 

 

 

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 PixelFormat 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 bitmap 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 CopyToClipboardAsDIB: Boolean;

Copies bitmap to clipboard, converting it to DIB format first.

 

function CopyToClipboard: Boolean;

Copies bitmap to clipboard. When Handle = 0, CLIPBOARD is emptied!!!

 

function PasteFromClipboard: Boolean;

Takes CF_DIB format bitmap from clipboard and assigns it to the TBitmap object.

 

 

function LoadMappedBitmap( hInst: THandle; BmpResID: Integer; const Map: array of TColor ): HBitmap;

This function can be used to load bitmap and replace some it colors to desired ones. This function especially useful when loaded by the such way bitmap is used as toolbar bitmap - to replace some original colors to system default colors. To use this function properly, the bitmap should be prepared as 16-color bitmap, which uses only system colors. To do so, create a new 16-color bitmap with needed dimensions in Borland Image Editor and paste a bitmap image, copied in another graphic tool, and then save it. If this is not done, bitmap will not be loaded correctly!

 

function LoadMappedBitmapEx( MasterObj: PObj; hInst: THandle; BmpResName: PKOLChar; const Map: array of TColor ): HBitmap;

by Alex Pravdin: like LoadMappedBitmap, but much powerful. It uses CreateMappedBitmapEx, so it understands any bitmap color format, including pf24bit. Also, LoadMappedBitmapEx provides auto-destroying loaded resource when MasterObj is destroyed.

 

function CreateMappedBitmap( Instance: THandle; Bitmap: Integer; Flags: UINT; ColorMap: PColorMap; NumMaps: Integer ): HBitmap; stdcall;

Creates mapped bitmap replacing colors correspondently to the ColorMap (each pare of colors defines color replaced and a color used for replace it in the bitmap). See also CreateMappedBitmapEx.

 

function CreateMappedBitmapEx( Instance: THandle; BmpRsrcName: PKOLChar; Flags: Cardinal; ColorMap: PColorMap; NumMaps: Integer ): HBitmap;