Sign in Join
Wiki copytemporary

BGRABitmap: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
11## Description
22
33**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).
44
55The main class is [[TBGRABitmap class|TBGRABitmap]], which is derived from [[fcl-image|TFPCustomImage]]. There is also [TBGRAPtrBitmap class](https://bgrabitmap.github.io/doc/BGRADefaultBitmap.TBGRAPtrBitmap.html) 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).
66
77The image can be rendered on a regular Canvas or on an [[BGRABitmap and OpenGL|OpenGL surface]].
88
99As of version 10, additional bitmap types are available:
1010
1111- [[TBGRABitmap class|TBGRABitmap]]: sRGB, 8 bit per channel.
1212- [TGrayscaleMask](https://bgrabitmap.github.io/doc/BGRAGrayscaleMask.TGrayscaleMask.html): linear 8 bit grayscale. It now has drawing functions, so you can prepare a mask in 8 bit per pixel, avoiding to consume memory.
1313- [TExpandedBitmap](https://bgrabitmap.github.io/doc/ExpandedBitmap.TExpandedBitmap.html): linear RGB, 16 bit per channel. It has more precision than [[TBGRABitmap class|TBGRABitmap]] and is linear, so that dmLinearBlend and dmDrawWithTransparency are equivalent.
1414- [TLinearRGBABitmap](https://bgrabitmap.github.io/doc/LinearRGBABitmap.TLinearRGBABitmap.html): linear RGB, 32 bit per channel (single precision float). It has even more precision. Not really recommended though as it uses a lot of memory.
1515- [TWordXYZABitmap](https://bgrabitmap.github.io/doc/WordXYZABitmap.TWordXYZABitmap.html): [[BGRABitmap XYZ|XYZ]], 16 bit per channel. Can store any real and reflect color with great precision.
1616- [TXYZABitmap](https://bgrabitmap.github.io/doc/XYZABitmap.TXYZABitmap.html): [[BGRABitmap XYZ|XYZ]], 32 bit per channel (single precision float). It has even more precision and also a wider range, so that it can store fluorescent colors and light sources that would otherwise saturate.
1717
1818## Additional packages
1919
2020Some package use BGRABitmap to provide controls with nice graphics:
2121
2222- BGLControls: provides TBGLVirtualScreen to draw on an OpenGL surface. This package is in BGRABitmap archive.
2323- [[BGRAControls]]: lablels wth shadows, beautiful buttons, shapes, etc.
2424- [[uE Controls]]: gauges, LEDs, etc.
2525- [[Material Design]]: Google material design guidelines based UI components.
2626- BGRAControlsFX[1](https://forum.lazarus.freepascal.org/index.php?topic=34534.0): controls rendering on OpenGL surface
2727
2828Some examples in the test folder use BGRAControls and BGLControls. You may need to install them to open these projects within Lazarus. See [[Install Packages]].
2929
3030### NoGUI, NoLCL
3131
3232BGRABitmap package has additional .lpk packages:
3333
3434- bgrabitmappack4nogui.lpk: it is in fact related to the LCL, but without graphic user interface (no GUI). So one can use for example LazFreeType with it.
3535
3636- bgrabitmappack4nolcl.lpk: it is completely independent from the LCL. There is no more font rendering (neither system rendering nor from TrueType files). Though with another program that has the LCL, you could prepare a TBGRAVectorizedFont, compute necessary glyphs, save it to a file with SaveGlyphsToFile. Then in the program without LCL, load the file with LoadGlyphsFromFile. Note that MSEgui provides system rendering of fonts, so this incorporated into an MSEgui program, you have the usual font rendering: [GitHub issue](https://github.com/bgrabitmap/bgrabitmap/issues/139#issuecomment-1672184739).
3737
3838## Using BGRABitmap
3939
4040### Tutorial
4141
4242- [[BGRABitmap tutorial|A series of tutorials to learn step by step]]
4343- [How to convert an application from TCanvas to BGRABitmap](http://www.youtube.com/watch?v=HGYSLgtYx-U)
4444- [[BGRABitmap tutorial TAChart|Using BGRABitmap to render a TAChart]]
4545- [[BGRABitmap AggPas|A series of projects demonstrating advanced capabilities similar to AggPas]]
4646- Examples in [GitHub](https://github.com/bgrabitmap)
4747
4848### Overview
4949
5050Functions have long names in order to be understandable. Almost everything is accessible as a function or using a property of the [[TBGRABitmap class|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](https://developer.mozilla.org/en/HTML:Canvas).
5151
5252Some special features require the use of units, but you may not need them :
5353
5454- [TBGRAMultishapeFiller](https://bgrabitmap.github.io/doc/BGRAPolygon.TBGRAMultishapeFiller.html) to have an antialiased junctions of polygons is in BGRAPolygon
5555- [TBGRATextEffect](https://bgrabitmap.github.io/doc/BGRATextFX.TBGRATextEffect.html) is in BGRATextFX
5656- 2D transformations are in [BGRATransform unit](https://bgrabitmap.github.io/doc/BGRATransform.html)
5757- [TBGRAScene3D](https://bgrabitmap.github.io/doc/BGRAScene3D.TBGRAScene3D.html) is in BGRAScene3D
5858- If you need to have layers, BGRALayers provides [TBGRALayeredBitmap](https://bgrabitmap.github.io/doc/BGRALayers.TBGRALayeredBitmap.html)
5959
6060Double-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.
6161
6262### BGRABitmapTypes unit reference
6363
6464- [[BGRABitmap Pixel types|Pixel types and functions]]: *TBGRAPixel*, *THSLAPixel*...
6565- [[BGRABitmap Types imported from Graphics|Types imported from Graphics]]: *TColor*, pen style...
6666- [[BGRABitmap Color definitions|Color definitions]]: *VGAColors*, *CSSColors*...
6767- [[BGRABitmap Geometry types|Geometry types]]: *TPointF*, Bezier curves, *TArcDef*...
6868- [[BGRABitmap Miscellaneous types|Miscellaneous types]]: font, image format, resampling...
6969- [[TBGRACustomBitmap and IBGRAScanner]]: the base class for *TBGRABitmap* and scanners
7070
7171### Installation
7272
7373After unpacking a checkout, BGRA often does not compile in Linux. Try using the IDE Macro
7474
75-` LCLWidgetType:=gtk2`
75+``` pascal
76+ LCLWidgetType:=gtk2
77+```
7678
7779in such cases. Still some other part may not compile.
7880
7981See [[BGRA Installation on Linux]] for step-by-step installation instructions.
8082
8183### Simple example
8284
8385Create 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.
8486
8587``` pascal
8688Uses
8789 Classes, SysUtils, BGRABitmap, BGRABitmapTypes;
8890```
8991
9092The 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 class|TBGRABitmap]] object:
9193
9294``` pascal
9395var
9496 bmp: TBGRABitmap;
9597begin
9698 bmp := TBGRABitmap.Create(100, 100, BGRABlack); // creates a 100x100 pixels image with black background
9799
98100 bmp.FillRect(20, 20, 60, 60, BGRAWhite, dmSet); // draws a white square without transparency
99101 bmp.FillRect(40, 40, 80, 80, BGRA(0, 0, 255, 128), dmDrawWithTransparency); // draws a transparent blue square
100102 ...
101103end;
102104```
103105
104106Finally to show the bitmap:
105107
106108``` pascal
107109procedure TFMain.FormPaint(Sender: TObject);
108110begin
109111 bmp.Draw(Canvas, 0, 0, True); // draw the bitmap in opaque mode (faster)
110112end;
111113```
112114
113115See a full source code in [[BGRABitmap tutorial 1|tutorial 1]].
114116
115117## Notions
116118
117119Pixels 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.
118120
119121There 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.
120122
121123BGRABitmap functions propose 4 modes:
122124
123125- dmSet : replaces the four bytes of the drawn pixel, transparency not handled
124126- dmDrawWithTransparency : draws with alphablending and with gamma correction (see below)
125127- dmFastBlend or dmLinearBlend : draws with alphablending but without gamma correction (faster but entails color distortions with low intensities).
126128- dmXor : apply Xor to each component including alpha (if you want to invert color but keep alpha, use BGRA(255,255,255,0) )
127129
128130## Integrated drawing functions
129131
130132- draw/erase pixels
131133- draw a line with or without antialiasing
132134- floating point coordinates
133135- floating point pen width
134136- rectangle (frame or fill)
135137- ellipse and polygons with antialiasing
136138- spline computation (rounded curve)
137139- simple fill (Floodfill) or progressive fill
138140- color gradient rendering (linear, radial...)
139141- round rectangles
140142- texts with transparency
141143
142144## Drawing with the Canvas
143145
144146It 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.
145147
146148## Direct access to pixels
147149
148150To 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.
149151
150152``` pascal
151153var
152154 bmp: TBGRABitmap;
153155 p: PBGRAPixel;
154156 n: integer;
155157
156158begin
157159 bmp := TBGRABitmap.Create('image.png');
158160 p := bmp.Data;
159161 for n := bmp.NbPixels-1 downto 0 do
160162 begin
161163 p^.red := not p^.red; // invert red channel
162164 inc(p);
163165 end;
164166 bmp.InvalidateBitmap; // note that we have accessed pixels directly
165167 bmp.Draw(Canvas, 0, 0, True);
166168 bmp.Free;
167169end;
168170```
169171
170172It 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.
171173
172174See also the comparison between [[Fast direct pixel access|direct pixel access methods]].
173175
174176### InvalidateBitmap
175177
176178Basically, 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.
177179
178180To 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.
179181
180182## Image manipulation
181183
182184Available filters (prefixed with Filter) :
183185
184186- Radial blur : non directional blur
185187- Motion blur : directional blur
186188- Custom blur : blur according to a mask
187189
188190- Median : computes the median of colors around each pixel, which softens corners
189191- Pixelate : simplifies the image with rectangles of the same color
190192- Smooth : soften whole image, complementary to Sharpen
191193- Sharpen : makes contours more accute, complementary to Smooth
192194
193195- Contour : draws contours on a white background (like a pencil drawing)
194196- Emboss : draws contours with shadow
195197- EmbossHighlight : draws contours of a selection defined with grayscale
196198
197199- Grayscale : converts colors to grayscale with gamma correction
198200- Normalize : uses whole range of color luminosity
199201
200202- Rotate : rotation of the image around a point
201203- Sphere : distorts the image to make it look like projected on a sphere
202204- Twirl : distorts the image with a twirl effect
203205- Cylinder : distorts the image to make it look like projected on a cylinder
204206- Plane : computes a high precision projection on a horizontal plane. This is quite slow.
205207- SmartZoom3 : resizes the image x3 and detects borders, to have a useful zoom with ancient games sprites
206208
207209Some functions are not prefixed with Filter, because they do not return a newly allocated image. They modify the image in-place :
208210
209211- VerticalFlip : flips the image vertically
210212- HorizontalFlip : flips the image horizontally
211213- Negative : inverse of colors
212214- LinearNegative : inverse without gamma correction
213215- SwapRedBlue : swap red and blue channels (to convert between BGRA and RGBA)
214216- ConvertToLinearRGB : to convert from sRGB to RGB. Note the format used by BGRABitmap is sRGB when using dmDrawWithTransparency and RGB when using dmLinearBlend.
215217- ConvertFromLinearRGB : convert from RGB to sRGB.
216218
217219## Images combination
218220
219221[PutImage](https://bgrabitmap.github.io/doc/BGRABitmapTypes.TBGRACustomBitmap.html#PutImage-integer-integer-TBitmap-TDrawMode-byte-) is the basic image drawing function and [BlendImage](https://bgrabitmap.github.io/doc/BGRABitmapTypes.TBGRACustomBitmap.html#BlendImage-integer-integer-TBGRACustomBitmap-TBlendOperation-) allows to combine images, like layers of image editing softwares. Available modes are the following:
220222
221223- LinearBlend : simple superimposition without gamma correction (equivalent to dmFastBlend)
222224- Transparent : superimposition with gamma correction
223225- Multiply : multiplication of color values (with gamma correction)
224226- LinearMultiply : multiplication of color values (without gamma correction)
225227- Additive : addition of color values (with gamma correction)
226228- LinearAdd : addition of color values (without gamma correction)
227229- Difference : difference of color values (with gamma correction)
228230- LinearDifference : difference of color values (without gamma correction)
229231- Negation : makes common colors disappear (with gamma correction)
230232- LinearNegation : makes common colors disappear (without gamma correction)
231233- Reflect, Glow : for light effects
232234- ColorBurn, ColorDodge, Overlay, Screen : misc. filters
233235- Lighten : keeps the lightest color values
234236- Darken : keeps the darkest color values
235237- Xor : exclusive or of color values
236238
237239These modes can be used in TBGRALayeredBitmap, which makes it easier because BlendImage only provides the basic blending operations.
238240
239241## Screenshots
240242
241243![](/wiki-images/5/5d/Lazpaint_contour.png) ![](/wiki-images/2/25/Lazpaint_curve_redim.png) ![](/wiki-images/2/23/Bgra_wirecube.png) ![](/wiki-images/b/b0/Bgra_chessboard.jpg)
242244
243245## Licence
244246
245247modified LGPL
246248
247249Author: [Juliette ELSASS](http://johann-elsass.net) ([Facebook](http://www.facebook.com/johann.elsass.1))
248250
249251## Download
250252
251253Latest version: <https://github.com/bgrabitmap/bgrabitmap/releases>
252254
253255Sourceforge with [[LazPaint]]: <http://sourceforge.net/projects/lazpaint/files/src/>
254256
255257GitHub: <https://github.com/bgrabitmap/>
256258
257259## See also
258260
259261- [[Developing with Graphics]]
260262
261263---
262264*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](/wiki-contact).*
263265Category: BGRABitmap
264266Category: Components
265267Category: Graphics

Back to history