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

Pixel functions

function PtInClipRect(x, y: int32or64): boolean; inline;
Checks if the specified point is in the clipping rectangle ClipRect
procedure SetPixel(x, y: int32or64; c: TColor); override;
Sets the pixel by replacing the content at (x,y) with the specified color. Alpha value is set to 255 (opaque)
procedure SetPixel(x, y: int32or64; c: TBGRAPixel); override;
Sets the pixel at (x,y) with the specified content
procedure XorPixel(x, y: int32or64; c: TBGRAPixel); override;
Applies a logical xor to the content of the pixel with the specified value. This includes the alpha channel, so if you want to preserve the opacity, provide a color c with alpha channel equal to zero
procedure DrawPixel(x, y: int32or64; c: TBGRAPixel); override;
Draws a pixel with gamma correction at (x,y). Pixel is supplied in sRGB colorspace
procedure DrawPixel(x, y: int32or64; ec: TExpandedPixel); override;
Draws a pixel with gamma correction at (x,y). Pixel is supplied in gamma expanded colorspace
procedure FastBlendPixel(x, y: int32or64; c: TBGRAPixel); override;
Draws a pixel without gamma correction at (x,y). Pixel is supplied in sRGB colorspace
procedure ErasePixel(x, y: int32or64; alpha: byte); override;
Erase the content of the pixel by reducing the value of the alpha channel. If the resulting alpha reaches zero, the content is replaced by BGRAPixelTransparent
procedure AlphaPixel(x, y: int32or64; alpha: byte); override;
Sets the alpha value at (x,y). If alpha = 0, the pixel is replaced by BGRAPixelTransparent
function GetPixel(x, y: int32or64): TBGRAPixel; override;
Returns the content of the specified pixel. If it is out of the bounds of the picture, the result is BGRAPixelTransparent
function GetPixel(x, y: single; AResampleFilter: TResampleFilter = rfLinear; smoothBorder: boolean = true): TBGRAPixel; override;
Computes the value of the pixel at a floating point coordiante by interpolating the values of the pixels around it.
There is a one pixel wide margin around the pixel where the pixels are still considered inside. If smoothBorder is set to true, pixel fade to transparent.
If it is more out of the bounds, the result is BGRAPixelTransparent.
AResampleFilter specifies how pixels must be interpolated. Accepted values are rfBox, rfLinear, rfHalfCosine and rfCosine
function GetPixel256(x, y, fracX256,fracY256: int32or64; AResampleFilter: TResampleFilter = rfLinear; smoothBorder: boolean = true): TBGRAPixel; override;
Similar to previous GetPixel function, but the fractional part of the coordinate is supplied with a number from 0 to 255. The actual coordinate is (x + fracX256/256, y + fracY256/256)
function GetPixelCycle(x, y: single; AResampleFilter: TResampleFilter = rfLinear): TBGRAPixel; override;
Computes the value of the pixel at a floating point coordiante by interpolating the values of the pixels around it. If the pixel is out of bounds, the image is repeated.
AResampleFilter specifies how pixels must be interpolated. Accepted values are rfBox, rfLinear, rfHalfCosine and rfCosine
function GetPixelCycle256(x, y, fracX256,fracY256: int32or64; AResampleFilter: TResampleFilter = rfLinear): TBGRAPixel; override;
Similar to previous GetPixel function, but the fractional part of the coordinate is supplied with a number from 0 to 255. The actual coordinate is (x + fracX256/256, y + fracY256/256)
function GetPixelCycle(x, y: single; AResampleFilter: TResampleFilter; repeatX: boolean; repeatY: boolean): TBGRAPixel; override;
Computes the value of the pixel at a floating point coordiante by interpolating the values of the pixels around it. repeatX and repeatY specifies if the image is to be repeated or not.
AResampleFilter specifies how pixels must be interpolated. Accepted values are rfBox, rfLinear, rfHalfCosine and rfCosine
function GetPixelCycle256(x, y, fracX256,fracY256: int32or64; AResampleFilter: TResampleFilter; repeatX: boolean; repeatY: boolean): TBGRAPixel; override;
Similar to previous GetPixel function, but the fractional part of the coordinate is supplied with a number from 0 to 255. The actual coordinate is (x + fracX256/256, y + fracY256/256)

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.