TBGRABitmap class

From Lazarus wiki
Jump to navigationJump to search

Back to BGRABitmap.

TBGRABitmap class contains an image stored in BGRA 32-bit format. It derives from TBGRADefaultBitmap which derives from TBGRACustomBitmap from which it inherits its properties. So it implements the interface IBGRAScanner which allows it to be used as a texture (like a brush).

Implementations

TBGRABitmap is a shortcut provided by BGRABitmap unit for the active implementation, depending on the widgetset. It can be one of the following:

  • TBGRAWinBitmap on Windows
  • TBGRAGtkBitmap on Gtk
  • TBGRAQtBitmap when Qt widget is active
  • TBGRAfpGUIBitmap when using the package for fpGUI toolkit (bgrabitmappack4fpgui.lpk)
  • TBGRANoGUIBitmap when using the package independent of the graphic user interface (bgrabitmappack4nogui.lpk)
  • TBGRADefaultBitmap otherwise

Direct pixel access

The image is stored as BGRA 32-bit:

PBGRAPixel = ^TBGRAPixel;
Pointer for direct pixel access. Data is stored as a sequence of TBGRAPixel. See BGRABitmap tutorial 4
TBGRAPixel = packed record blue, green, red, alpha: byte; end;
Each pixel is a sequence of 4 bytes containing blue, green, red and alpha channel. Values range from 0 to 255, color is in sRGB colorspace. The alpha value of 0 is transparent and 255 is opaque

You can either use Data property if you want to go through all pixels, or ScanLine property if you want to do something that depends on the line number. Data returns the first pixel in memory, so that you can read all the pixels from there by increasing the pointer (add 1 to PBGRAPixel). Otherwise, you can do a loop where y goes from 0 to Height-1, and for each line, retrieve with ScanLine the pointer of the beginning of the line. Then you can read all the pixels of the line from there by increasing the pointer.

The following properties of TBGRABitmap allow to access the data directly:

TBGRABitmap = class(TBGRACustomBitmap)
property Width: integer read;
Width of the image in pixels
property Height: integer read;
Height of the image in pixels
property NbPixels: integer read;
Total number of pixels. It is always true that NbPixels = Width * Height
property ScanLine[y: integer]: PBGRAPixel read;
Returns the address of the left-most pixel of any line. The parameter y ranges from 0 to Height-1
property LineOrder: TRawImageLineOrder read;
Indicates the order in which lines are stored in memory. If it is equal to riloTopToBottom, the first line is the top line. If it is equal to riloBottomToTop, the first line is the bottom line. See miscellaneous types
property Data: PBGRAPixel read;
Provides a pointer to the first pixel in memory. Depending on the LineOrder property, this can be the top-left pixel or the bottom-left pixel. There is no padding between scanlines, so the start of the next line is at the address Data + Width. See BGRABitmap tutorial 4
property Caption: string read write;
Can contain a text to describe the image. It is not displayed. It is the name of the layer if this image is in a layered bitmap.

TBGRABitmap reference

TBGRABitmap = class(TBGRACustomBitmap)
This class is the base for all TBGRABitmap classes. It implements most function to the exception from implementations specific to the widgetset
property CanvasBGRA: TBGRACanvas read;
Provides a canvas with opacity and antialiasing
property Canvas2D: TBGRACanvas2D read;
Provides a canvas with 2d transformation and similar to HTML5.

For more properties, see parent class TBGRACustomBitmap

Reference counting

function NewReference: TBGRACustomBitmap;
Adds a reference (this reference count is not the same as the reference count of an interface, it changes only by explicit calls
procedure FreeReference;
Free a reference. When the resulting reference count gets to zero, the image is freed. The initial reference count is equal to 1
function GetUnique: TBGRACustomBitmap;
Returns an object with a reference count equal to 1. Duplicate this bitmap if necessary

Constructors

constructor Create(AWidth, AHeight: integer); override;
Creates a new bitmap, initialize properties and bitmap data
procedure SetSize(AWidth, AHeight: integer); override;
Can only be called with an existing instance of TBGRABitmap. Sets the dimensions of an existing TBGRABitmap instance.
constructor Create; override;
Creates an image of width and height equal to zero. In this case, Data = nil
constructor Create(AFPImage: TFPCustomImage); override;
Creates an image by copying the content of a TFPCustomImage
constructor Create(ABitmap: TBitmap); override;
Creates an image by copying the content of a TBitmap
constructor Create(AWidth, AHeight: integer; Color: TColor); override;
Creates an image of dimensions AWidth and AHeight and fills it with the opaque color Color
constructor Create(AWidth, AHeight: integer; Color: TBGRAPixel); override;
Creates an image of dimensions AWidth and AHeight and fills it with Color
constructor Create(AFilename: string); override;
Creates an image by loading its content from the file AFilename. The encoding of the string is the default one for the operating system. It is recommended to use the next constructor and UTF8 encoding
constructor Create(AFilename: string; AIsUtf8: boolean); override;
Creates an image by loading its content from the file AFilename. The boolean AIsUtf8Filename specifies if UTF8 encoding is assumed for the filename
constructor Create(AStream: TStream); override;
Creates an image by loading its content from the stream AStream
destructor Destroy; override;
Free the object and all its resources
function NewBitmap(AWidth, AHeight: integer): TBGRACustomBitmap; override;
Can only be called from an existing instance of TBGRABitmap. Creates a new instance with dimensions AWidth and AHeight, containing transparent pixels.
function NewBitmap(AWidth, AHeight: integer; Color: TBGRAPixel): TBGRACustomBitmap; override;
Can only be called from an existing instance of TBGRABitmap. Creates a new instance with dimensions AWidth and AHeight, and fills it with Color
function NewBitmap(Filename: string): TBGRACustomBitmap; override;
Can only be called from an existing instance of TBGRABitmap. Creates a new instance with by loading its content from the file Filename. The encoding of the string is the default one for the operating system
function NewBitmap(Filename: string; AIsUtf8: boolean): TBGRACustomBitmap; override;
Can only be called from an existing instance of TBGRABitmap. Creates a new instance with by loading its content from the file Filename
procedure Assign(Source: TPersistent); override;
Assign the content of the specified Source. It can be a TBGRACustomBitmap or a TFPCustomImage
procedure Serialize(AStream: TStream); override;
Stores the image in the stream without compression nor header
procedure Deserialize(AStream: TStream); override;
Reads the image in a stream that was previously serialized
class procedure SerializeEmpty(AStream: TStream);
Stores an empty image (of size zero)

Example:

var bmp1, bmp2: TBGRABitmap;
begin
  bmp1 := TBGRABitmap.Create(100,100);
  bmp2 := bmp1.NewBitmap(100,100) as TBGRABitmap;
  ...
end;

See tutorial 2 on how to load and display an image.
See reference on loading and saving files

Text fonctions

class TBGRABitmap
  property FontName: string; read write;
  property FontStyle: TFontStyles; read write;
  property FontQuality : TBGRAFontQuality; read write;
  property FontOrientation: integer; read write;
  property FontHeight: integer; read write;
  property FontAntialias: Boolean; read write;
  property FontFullHeight: integer; read write;
  property FontPixelMetric: TFontPixelMetric;
  property FontRenderer: TBGRACustomFontRenderer; read write;

  procedure TextOut(x, y: single; sUTF8: string; c: TBGRAPixel; align: TAlignment);
  procedure TextOut(x, y: single; sUTF8: string; texture: IBGRAScanner; align: TAlignment);
  procedure TextOutAngle(x, y: single; orientationTenthDegCCW: integer; sUTF8: string; c: TBGRAPixel; align: TAlignment);
  procedure TextOutAngle(x, y: single; orientationTenthDegCCW: integer; sUTF8: string; texture: IBGRAScanner; align: TAlignment);
  procedure TextOut(x, y: single; sUTF8: string; c: TBGRAPixel);
  procedure TextOut(x, y: single; sUTF8: string; c: TColor);
  procedure TextOut(x, y: single; sUTF8: string; texture: IBGRAScanner);
  procedure TextRect(ARect: TRect; x, y: integer; sUTF8: string; style: TTextStyle; c: TBGRAPixel);
  procedure TextRect(ARect: TRect; x, y: integer; sUTF8: string; style: TTextStyle; texture: IBGRAScanner);
  procedure TextRect(ARect: TRect; sUTF8: string; halign: TAlignment; valign: TTextLayout; c: TBGRAPixel);
  procedure TextRect(ARect: TRect; sUTF8: string; halign: TAlignment; valign: TTextLayout; texture: IBGRAScanner);
  function TextSize(sUTF8: string): TSize;

See TBGRABitmap text functions.

Pixel functions

class TBGRABitmap
  procedure SetPixel(x, y: int32or64; c: TColor);
  procedure XorPixel(x, y: int32or64; c: TBGRAPixel);
  procedure SetPixel(x, y: int32or64; c: TBGRAPixel);
  procedure DrawPixel(x, y: int32or64; c: TBGRAPixel);
  procedure DrawPixel(x, y: int32or64; c: TBGRAPixel; ADrawMode: TDrawMode);
  procedure DrawPixel(x, y: int32or64; ec: TExpandedPixel);
  procedure FastBlendPixel(x, y: int32or64; c: TBGRAPixel);
  procedure ErasePixel(x, y: int32or64; alpha: byte);
  procedure AlphaPixel(x, y: int32or64; alpha: byte);
  function GetPixel(x, y: int32or64): TBGRAPixel;
  function GetPixel256(x, y, fracX256,fracY256: int32or64; AResampleFilter: TResampleFilter = rfLinear; smoothBorder: boolean = true): TBGRAPixel;
  function GetPixel(x, y: single; AResampleFilter: TResampleFilter = rfLinear; smoothBorder: boolean = true): TBGRAPixel;
  function GetPixelCycle(x, y: int32or64): TBGRAPixel;
  function GetPixelCycle(x, y: single; AResampleFilter: TResampleFilter = rfLinear): TBGRAPixel;
  function GetPixelCycle(x, y: single; AResampleFilter: TResampleFilter; repeatX: boolean; repeatY: boolean): TBGRAPixel;
  function GetPixelCycle256(x, y, fracX256,fracY256: int32or64; AResampleFilter: TResampleFilter = rfLinear): TBGRAPixel;
  function GetPixelCycle256(x, y, fracX256,fracY256: int32or64; AResampleFilter: TResampleFilter; repeatX: boolean; repeatY: boolean): TBGRAPixel;

See TBGRABitmap pixel functions.