Bitmap#

Qualified name: delphivcl.Bitmap

class Bitmap#

Bases: Graphic

TBitmap is an encapsulation of a Windows bitmap (HBITMAP), including its palette (HPALETTE). A bitmap is a powerful graphics object used to create, manipulate and store images in memory and as files on a disk. TBitmap contains an internal image of the bitmap graphic and automatically manages realization of the palette when drawn. To draw a bitmap on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TBitmap as a parameter. Creating copies of a TBitmap is very fast since the handle is copied rather than the image. If the image is modified and the handle is shared by more than one TBitmap object, the image is copied before the modification is performed (that is, copy on write).

Methods

`Assign`	Copies a new bitmap image to the bitmap object.
`CanLoadFromStream`	Vcl.Graphics.TBitmap.CanLoadFromStream inherits from Vcl.Graphics.TGraphic.CanLoadFromStream.
`Create`	Instantiates a bitmap object.
`Destroy`	Disposes of the instance of the bitmap object.
`Dormant`	Creates a memory bitmap image in order to release the bitmap handle, forcing the image into DIB format to save resources.
`FreeImage`	Frees the cached file image stored in memory by the bitmap.
`HandleAllocated`	Indicates whether the TBitmap object has acquired a handle to the underlying GDI object.
`LoadFromClipboardFormat`	Loads a bitmap from the Clipboard into the bitmap object.
`LoadFromResourceID`	Loads a bitmap from a resource into the bitmap object.
`LoadFromResourceName`	Loads a bitmap resource into the bitmap object.
`LoadFromStream`	Loads the bitmap from a stream into the bitmap object.
`Mask`	Converts the current bitmap image into a monochrome mask, replacing TransparentColor with white and every other color with black.
`ReleaseHandle`	Returns the handle to the bitmap so that the TBitmap object no longer knows about the handle.
`ReleaseMaskHandle`	Returns the handle to the bitmap's mask so that the TBitmap object no longer knows about the mask handle.
`ReleasePalette`	Returns the handle to the bitmap's palette and disassociates the palette from the TBitmap object.
`SaveToClipboardFormat`	Creates a local copy of the bitmap in Clipboard format.
`SaveToStream`	Saves the bitmap to a stream.
`SetSize`	Specifies the size of the bitmap.

Attributes

`AlphaFormat`	Indicates how reserved byte of each pixel is used in 32 bit bitmaps.
`Canvas`	Provides access to a drawing surface that represents the bitmap.
`ClassName`	Returns the TObject.ClassName
`Empty`	Indicates whether the graphics object contains a graphic.
`Handle`	Provides access to the Windows GDI bitmap handle for accessing the GDI bitmap object.
`HandleType`	Indicates whether the bitmap is a device-dependent bitmap, or a device-independent bitmap.
`Height`	Specifies the vertical size of the graphic in pixels.
`IgnorePalette`	Determines whether the bitmap realizes its palette when drawing its image.
`MaskHandle`	Provides access to the Windows GDI bitmap handle for accessing the GDI bitmap object.
`Modified`	Indicates whether the graphics object has been changed or edited.
`Monochrome`	Determines whether the bitmap displays its image in monochrome.
`OnChange`	<Delphi property OnChange of type TGraphic at 21141225010>
`OnProgress`	<Delphi property OnProgress of type TGraphic at 211412250E0>
`Palette`	Indicates the color palette of the graphical image.
`PaletteModified`	Indicates whether the palette has changed.
`PixelFormat`	Indicates the bit format of the bitmap image, specifying how the image is displayed and how the pixels of the bitmap image are stored in memory.
`ScaledDrawer`	Returns the reference to the scaled drawer.
`ScanLine`	<Delphi indexed property ScanLine of type TBitmap at 211416EE9A0>
`SupportsPartialTransparency`	Indicate whether graphic supports partial transparency or an alpha channel.
`Transparent`	Indicates whether the image covers its rectangular area.
`TransparentColor`	Determines which color of the bitmap is to be transparent when the bitmap is drawn.
`TransparentMode`	Determines whether the TransparentColor property's value is automatically calculated or stored with the bitmap object.
`Width`	Determines the maximum width of the graphics object in pixels.

AlphaFormat#: Indicates how reserved byte of each pixel is used in 32 bit bitmaps. Use AlphaFormat to change the way a TBitmap uses the reserved byte of each pixel in a 32bit Bitmap.

Assign(Source: Persistent)#

Copies a new bitmap image to the bitmap object. Assign copies the bitmap image contained in Source to the bitmap object. If Source is not a bitmap, Assign calls the inherited Assign method, which can copy an image from any class that knows how to copy to a TBitmap object. If the bitmap needs to be changed, the actual bitmap image is copied before the changes are made (copy on write).

Note: An object of one type can always be assigned to another object of the same type. Also, the Source can be of type TPicture if the Graphic property of the picture is a bitmap.

CanLoadFromStream(Stream: Stream) → Boolean#: Vcl.Graphics.TBitmap.CanLoadFromStream inherits from Vcl.Graphics.TGraphic.CanLoadFromStream. All content below this line refers to Vcl.Graphics.TGraphic.CanLoadFromStream. CanLoadFromStream returns True when a specified stream contains a streamed image of a specific TGraphic subclass. The method uses current stream position, it does not change current stream position.

Canvas#: Provides access to a drawing surface that represents the bitmap. Canvas allows drawing on the bitmap by providing a T Canvas object for this purpose. Drawing on the canvas effectively modifies the underlying bitmap image pixels. Any canvas operation is valid on a bitmap (not just Draw and StretchDraw) including line drawing, rectangles, and circles. The bitmap object is passed as a parameter to these methods. A canvas object is created automatically for the bitmap and the property is read-only.

Create()#: Instantiates a bitmap object. Call Create to instantiate a bitmap object at runtime. Create is also called automatically when a bitmap image is loaded into a TImage. Create allocates memory for a bitmap object, and calls the inherited Create. Then it creates a TBitmapImage as the internal image that represents the bitmap. Instantiates a bitmap object. Call Create to instantiate a bitmap object at runtime. Create is also called automatically when a bitmap image is loaded into a TImage. Create allocates memory for a bitmap object, and calls the inherited Create. Then it creates a TBitmapImage as the internal image that represents the bitmap.

Destroy()#: Disposes of the instance of the bitmap object. Destroy is the destructor for a TBitmap object. Do not call the destructor directly in an application. Instead, call Free. Free verifies that the bitmap object is not nil before it calls Destroy. Destroy releases the internal bitmap image (TBitmapImage object) and frees the canvas before calling the inherited destructor.

Dormant()#: Creates a memory bitmap image in order to release the bitmap handle, forcing the image into DIB format to save resources. Use Dormant to change the format of the bitmap in memory thereby reducing the amount of GDI resources used by the application. Dormant creates a bitmap image in memory using a memory stream object. This preserves the image so that the bitmap can then free the HBITMAP (accessed through the Handle property) that was assigned to it. DIB handles may use fewer Win95 GDI resources than DDB, but DIBs may also use more memory than DDBs, depending on the current video driver and mode.

FreeImage()#

Frees the cached file image stored in memory by the bitmap. Use FreeImage to reduce the memory requirements of an application when color depth and pixel format are not an issue. Freeing the image releases the memory allocated for the bitmap image when it was originally loaded to disk. Consequently, some of the original pixel format of the bitmap is lost (for example, if you changed its format to a DIB) as well as the color depth of the bitmap. When a bitmap is loaded into a bitmap object, the bitmap object creates an image of the loaded bitmap in memory. If the bitmap isn’t changed, the memory image is used when saving the bitmap, to verify that the bitmap has not lost color depth or changed the pixel format.

Code Examples LoadFromFile (Delphi) LoadFromFile (C++)

Handle#

Provides access to the Windows GDI bitmap handle for accessing the GDI bitmap object. Use Handle to call a Windows API function that requires the handle of a bitmap object (HBITMAP). Pass Handle as the bitmap handle parameter to these functions. Handle is the HBITMAP encapsulated by the bitmap object. Avoid grabbing the handle directly since it causes the HBITMAP to be copied if more than one TBitmap shares the handle.

Warning: Be careful when giving the handle to an object or routine. If the receiver takes ownership (and destroys) the bitmap handle, call ReleaseHandle.

HandleAllocated()#: Indicates whether the TBitmap object has acquired a handle to the underlying GDI object. Use HandleAllocated to determine whether the Handle property is set to an HBITMAP value. HandleAllocated indicates whether the underlying GDI object has already been created. Use HandleAllocated rather than reading the Handle property. When an application reads the Handle property, it automatically creates a bitmap and returns its handle if the underlying GDI object does not already exist.

HandleType#: Indicates whether the bitmap is a device-dependent bitmap, or a device-independent bitmap. HandleType is used to find or modify the type of the bitmap. Device-dependent bitmaps (DDBs) may be faster to draw on the screen, but may be stored in memory in a device-specific format. Device-independent bitmaps (DIBs) are stored in memory in a standard format supported by all devices (including printers).

IgnorePalette#

Determines whether the bitmap realizes its palette when drawing its image. Use IgnorePalette when speed of drawing is a priority. When IgnorePalette is true, the bitmap does not realize its palette when drawing itself, resulting in lower picture quality on 256-color video drivers, but faster drawing of the bitmap image.

Note:

LoadFromClipboardFormat(AFormat: Word, AData: NativeUInt, APalette: HPALETE)#

Loads a bitmap from the Clipboard into the bitmap object. LoadFromClipboardFormat is called if the bitmap is registered with the TPicture object using the RegisterClipboardFormat method. LoadFromClipboardFormat replaces the current image with the data pointed to by the AData parameter. The palette for the bitmap is specified by the APalette parameter. The following code snippet shows how to load a bitmap from the clipboard and use that picture to draw on the canvas of the form.

Note: To load a bitmap into the clipboard, you can use the code snippet for the SaveToClipboardFormat method.

Delphi:

uses: Vcl.Clipbrd;

procedure TForm1.Button1Click(Sender: TObject); var

Bitmap : TBitmap;

begin

Bitmap := TBitMap.Create; try

Bitmap.LoadFromClipBoardFormat(cf_BitMap, ClipBoard.GetAsHandle(cf_Bitmap), 0); Canvas.draw(0,0,Bitmap);

finally: Bitmap.Free; Clipboard.Clear;

end;

C++:

#include <Vcl.Clipbrd.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender){

TBitmap* Bitmap; TClipboard* cb = Clipboard();

Bitmap = new TBitmap(); try{

Bitmap->LoadFromClipboardFormat(CF_BITMAP, cb->GetAsHandle(CF_BITMAP), 0); Canvas->Draw(0,0,Bitmap);

} __finally{

delete Bitmap; cb->Clear();

}

LoadFromResourceID(Instance: NativeUInt, ResID: Integer)#: Loads a bitmap from a resource into the bitmap object. Use LoadFromResourceID to load a specified bitmap resource along with palette information from a module’s executable file. Instance is the handle of the module that contains the resource. ResID is the resource ID for the bitmap.

LoadFromResourceName(Instance: NativeUInt, ResName: string)#

Loads a bitmap resource into the bitmap object. LoadFromResourceName loads the specified bitmap resource along with palette information from a module’s executable file. Instance is the handle of the module that contains the resource. ResName is the name of the resource to load.

Note: Use this routine to load bitmaps from RES files instead of the LoadBitmap API. LoadBitmap does not support 256-color images.

LoadFromStream(Stream: Stream)#: Loads the bitmap from a stream into the bitmap object. Use LoadFromStream to load the bitmap image from a stream. The Stream parameter specifies the stream from which to read the bitmap image. For example, use LoadFromStream to load a bitmap image from a BLOB stream that reads from a graphic field in a dataset.

Mask(TransparentColor: Color)#: Converts the current bitmap image into a monochrome mask, replacing TransparentColor with white and every other color with black. Use Mask to produce a monochrome mask bitmap based on a given transparent color. Mask produces the same image that MaskHandle does, except that the resulting mask image replaces the image in the TBitmap object, so it only makes sense to call Mask once. Use MaskHandle when only a bitmap handle of the mask image is needed.

MaskHandle#: Provides access to the Windows GDI bitmap handle for accessing the GDI bitmap object. Use MaskHandle to call a Windows API function that requires the handle of a bitmap object. Pass MaskHandle as the bitmap handle parameter to these functions. MaskHandle is the HBITMAP encapsulated by the bitmap object’s mask.

Monochrome#

Determines whether the bitmap displays its image in monochrome. If Monochrome is true if the bitmap displays as a monochrome bitmap. Monochrome is false if the bitmap displays in color, that is, if it contains more than one bit per pixel.

Note: Code Examples LoadFromFile (Delphi) LoadFromFile (C++)

PixelFormat#

Indicates the bit format of the bitmap image, specifying how the image is displayed and how the pixels of the bitmap image are stored in memory. Use PixelFormat to change a TBitmap’s internal image to a particular memory format and color depth, or to find out what memory format and color depth a TBitmap is using. The possible formats are specified in TPixelFormat. For example, PixelFormat can be used to set the pixel format of the bitmap image to 8-bit for video drivers that cannot display the native format of a bitmap image.

Note: The PixelFormat of a JPEG image object applies to the bitmap if the JPEG image is copied to it. Changing the pixel format is most commonly used with ScanLine, because your code must decode the pixel data accessed by ScanLine. Image-editing tools usually use one pixel for all internal image operations and copy the results to the screen (in whatever format) as the last step.

ReleaseHandle()#: Returns the handle to the bitmap so that the TBitmap object no longer knows about the handle. Use ReleaseHandle to disassociate the bitmap from the bitmap handle. Use it when you need to give a bitmap handle to a routine or object that will assume ownership (or destroy) the bitmap handle.

ReleaseMaskHandle()#: Returns the handle to the bitmap’s mask so that the TBitmap object no longer knows about the mask handle. Use ReleaseMaskHandle to disassociate the bitmap object from the bitmap mask handle.

ReleasePalette()#: Returns the handle to the bitmap’s palette and disassociates the palette from the TBitmap object. Use ReleasePalette to disassociate the palette from the bitmap image.

SaveToClipboardFormat(Format: Word, Data: NativeUInt, APalette: HPALETE)#

Creates a local copy of the bitmap in Clipboard format. Use SaveToClipboardFormat to copy the bitmap to a Clipboard format. The bitmap’s palette is returned in the APalette parameter, the format in the AFormat parameter, and a handle to the data in the AData parameter. Before the bitmap can be saved, an application must have registered the format with the TBitmap object using the RegisterClipboardFormat method. The following code snippet shows how to save a bitmap to the clipboard.

Note: To load a bitmap from the clipboard, you can use the code snippet for the LoadFromClipboardFormat method.

Delphi:

uses: Vcl.Clipbrd;

procedure TForm1.Button1Click(Sender: TObject); var

MyFormat : Word; Bitmap : TBitMap; AData : THandle; APalette : HPALETTE;

begin

Bitmap := TBitmap.Create; try

Bitmap.LoadFromFile(‘C:UsersPublicPicturesSample Picturesdesert.bmp’); Bitmap.SaveToClipBoardFormat(MyFormat, AData, APalette); ClipBoard.SetAsHandle(MyFormat,AData);

finally: Bitmap.Free;

end;

C++:

#include <Vcl.Clipbrd.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender){

TClipboard* cb = Clipboard(); unsigned short MyFormat; TBitmap* Bitmap; unsigned int AData; HPALETTE APalette;

Bitmap = new TBitmap(); try{

Bitmap->LoadFromFile(“C:\Users\Public\Pictures\Sample Pictures\desert.bmp”); Bitmap->SaveToClipboardFormat(MyFormat, AData, APalette); cb->SetAsHandle(MyFormat, AData);

} __finally{

delete Bitmap;

}

SaveToStream(Stream: Stream)#: Saves the bitmap to a stream. Use SaveToStream to write the bitmap image to the stream specified by the Stream parameter. For example, specify a TBlobStream object as the Stream parameter to save the bitmap image to a graphic field in a dataset.

ScanLine#: <Delphi indexed property ScanLine of type TBitmap at 211416EE9A0>

SetSize(AWidth: Integer, AHeight: Integer)#: Specifies the size of the bitmap. Use the SetSize method to set both the height and width of the bitmap. This results in better performance than setting the height and width separately.

TransparentColor#: Determines which color of the bitmap is to be transparent when the bitmap is drawn. Use TransparentColor to determine how to draw the bitmap transparently. When the TransparentMode property is set to tmAuto (default), TransparentColor returns the color of the first pixel in the bitmap image data. For “bottom-up” bitmaps, the first pixel is the bottom leftmost pixel shown onscreen. For “top-down” bitmaps (less common), the first pixel is in the top left corner shown onscreen. If TransparentColor is assigned, the TransparentMode is automatically set to tmFixed so that the new transparent color can be used later. If you want TransparentColor to disregard any assignments and return the bottom leftmost pixel color again, set TransparentMode to tmAuto.

TransparentMode#: Determines whether the TransparentColor property’s value is automatically calculated or stored with the bitmap object. When TransparentMode is set to tmAuto (the default), the TransparentColor property returns the color of the bottom-leftmost pixel of the bitmap image. When TransparentMode is set to tmFixed, the TransparentColor property refers to the color stored in the bitmap object.