Sign in Join
Wiki copytemporary

BGRABitmap

Deutsch · English · Español · Français · Русский · 中文（中国）

Description

BGRABitmap is a set of units designed to modify and create images with transparency (alpha channel). Direct pixel access allows fast image processing. The library has been tested on Windows, Ubuntu and macOS, with widgetsets win32, gtk1, gtk2, Carbon (32 bit) and Cocoa (64 bit).

The main class is TBGRABitmap, which is derived from TFPCustomImage. There is also TBGRAPtrBitmap class which allows to edit BGRA data that are already allocated. This format consists of 4 bytes for each pixel (blue, green, red and alpha in that order on Windows).

The image can be rendered on a regular Canvas or on an OpenGL surface.

As of version 10, additional bitmap types are available:

Additional packages

Some package use BGRABitmap to provide controls with nice graphics:

Some examples in the test folder use BGRAControls and BGLControls. You may need to install them to open these projects within Lazarus. See Install Packages.

NoGUI, NoLCL

BGRABitmap package has additional .lpk packages:

Using BGRABitmap

Tutorial

Overview

Functions have long names in order to be understandable. Almost everything is accessible as a function or using a property of the TBGRABitmap object. For example, you can use CanvasBGRA to have some canvas similar to TCanvas (with opacity and antialiasing) and Canvas2D to have the same features as the HTML canvas.

Some special features require the use of units, but you may not need them :

Double-buffering is not really part of BGRABitmap, because it is more about how to handle forms. To do double-buffering, you can use TBGRAVirtualScreen which is in the BGRAControls package. Apart from that, double-buffering in BGRABitmap works like any double-buffering. You need to have a bitmap where you store your drawing and that you display with a single Draw instruction.

BGRABitmapTypes unit reference

Installation

After unpacking a checkout, BGRA often does not compile in Linux. Try using the IDE Macro

pascal
 LCLWidgetType:=gtk2

in such cases. Still some other part may not compile.

See BGRA Installation on Linux for step-by-step installation instructions.

Simple example

Create a project and open bgrabitmappackage.lpk with Lazarus. In the package window, click on "Use > Add to Project". Then in the source code of the main file (main form or main program), add to uses clause BGRABitmap units. You may need to add BGRAGraphics unit as well if you use certain types that are inherited from the LCL.

pascal
Uses 
  Classes, SysUtils, BGRABitmap, BGRABitmapTypes;

The unit BGRABitmapTypes contains common definitions, but one can declare only BGRABitmap in order to load and show a bitmap. Then, the first step is to create a TBGRABitmap object:

pascal
var
  bmp: TBGRABitmap;
begin
  bmp := TBGRABitmap.Create(100, 100, BGRABlack); // creates a 100x100 pixels image with black background

  bmp.FillRect(20, 20, 60, 60, BGRAWhite, dmSet); // draws a white square without transparency
  bmp.FillRect(40, 40, 80, 80, BGRA(0, 0, 255, 128), dmDrawWithTransparency); // draws a transparent blue square
  ...
end;

Finally to show the bitmap:

pascal
procedure TFMain.FormPaint(Sender: TObject);
begin
  bmp.Draw(Canvas, 0, 0, True); // draw the bitmap in opaque mode (faster)
end;

See a full source code in tutorial 1.

Notions

Pixels in a bitmap with transparency are stored with 4 values, here 4 bytes in the order Blue, Green, Red, Alpha. The last channel defines the level of opacity (0 signifies transparent, 255 signifies opaque), other channels define color and luminosity.

There are basically two drawing modes. The first consists in replacing the content of the pixel information, the second consists in blending the pixel already here with the new one, which is called alpha blending.

BGRABitmap functions propose 4 modes:

Integrated drawing functions

Drawing with the Canvas

It is possible to draw with a Canvas object, with usual functions but without antialiasing. Opacity of drawing is defined by the CanvasOpacity property. This way is slower because it needs image transformations. If you can, use CanvasBGRA instead, which allows transparency and antialiasing while having the same function names as with TCanvas.

Direct access to pixels

To access pixels, there are two properties, Data and Scanline. The first gives a pointer to the first pixel of the image, and the second gives a pointer to the first pixel of a given line.

pascal
var 
  bmp: TBGRABitmap;
  p: PBGRAPixel;
  n: integer;

begin
  bmp := TBGRABitmap.Create('image.png');
  p := bmp.Data;
  for n := bmp.NbPixels-1 downto 0 do
  begin
    p^.red := not p^.red; // invert red channel
    inc(p);
  end;
  bmp.InvalidateBitmap;   // note that we have accessed pixels directly
  bmp.Draw(Canvas, 0, 0, True);
  bmp.Free;
end;

It is necessary to call the function InvalidateBitmap to rebuild the image in a next call to Draw for example. Notice that the line order can be reverse, depending on the LineOrder property.

See also the comparison between direct pixel access methods.

InvalidateBitmap

Basically, BGRABitmap can store an image that may not be drawable as such, not a bitmap object of the system. In order to keep track of changes, the function InvalidateBitmap is called whenever pixel data is modified. So when the bitmap object is requested, the library knows that it needs to be rebuilt.

To sum up, the only time a regular user would call this function is after modifying pixels pointed to by Data / ScanLine directly and before drawing the bitmap or requesting the bitmap object.

Image manipulation

Available filters (prefixed with Filter) :

Some functions are not prefixed with Filter, because they do not return a newly allocated image. They modify the image in-place :

Images combination

PutImage is the basic image drawing function and BlendImage allows to combine images, like layers of image editing softwares. Available modes are the following:

These modes can be used in TBGRALayeredBitmap, which makes it easier because BlendImage only provides the basic blending operations.

Screenshots

Licence

modified LGPL

Author: Juliette ELSASS (Facebook)

Download

Latest version: https://github.com/bgrabitmap/bgrabitmap/releases

Sourceforge with LazPaint: http://sourceforge.net/projects/lazpaint/files/src/

GitHub: https://github.com/bgrabitmap/

See also

From the Free Pascal wiki, page "BGRABitmap", as it stood on 2024-04-03 after a change by Circular, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.

Revision 2, last changed by WikiArchive .

Talk about this page

Nobody has opened a bench for this page yet. Sign in to open one.