TBGRABitmap class

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 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(TBGRADefaultBitmap)
	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

TBGRADefaultBitmap = 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. Example: var bmp1, bmp2: TBGRABitmap; begin bmp1 := TBGRABitmap.Create(100,100); bmp2 := bmp1.NewBitmap(100,100) as TBGRABitmap; ... end;
	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

See tutorial 2 on how to load and display an image

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.