BGRABitmap tutorial 4: what changed

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

Old	New		Line
1	1		This tutorial shows you how to access directly to pixels. See reference on [[TBGRABitmap class\|direct pixel access]].
2	2
3	3		## Create a new project
4	4
5	5		Create a new project and add a reference to [[BGRABitmap]], the same way as in [[BGRABitmap tutorial\|the first tutorial]].
6	6
7	7		### Add a painting handler
8	8
9	9		With the object inspector, add an OnPaint handler and write:
10	10
11	11		``` pascal
12	12		procedure TForm1.FormPaint(Sender: TObject);
13	13		var
14	14		x, y: integer;
15	15		p: PBGRAPixel;
16	16		image: TBGRABitmap;
17	17		begin
18	18		image := TBGRABitmap.Create(ClientWidth, ClientHeight);
19	19
20	20		for y := 0 to image.Height-1 do
21	21		begin
22	22		p := image.Scanline[y];
23	23		for x := 0 to image.Width-1 do
24	24		begin
25	25		p^.red := x * 256 div image.Width;
26	26		p^.green := y * 256 div image.Height;
27	27		p^.blue := 0;
28	28		p^.alpha := 255;
29	29		inc(p);
30	30		end;
31	31		end;
32	32		image.InvalidateBitmap; // changed by direct access
33	33
34	34		image.Draw(Canvas, 0, 0, True);
35	35		image.free;
36	36		end;
37	37		```
38	38
39	39		This procedure creates a bitmap of the same size as the available client space. Then the loops access directly to pixel data to render a bidimensional gradient. Finally the image is drawn and freed.
40	40
41	41		To access to bitmap data, you can either use Data, if you do not mind the line order, or Scanline to access to a specific line. Within a line, pixels are ordered from left to right. Each component is defined. For example:
42	42
43	43		``` pascal
44	44		p^.red := x*256 div image.Width;
45	45		```
46	46
47	47		Defines a red component varying from 0 to 255 from left to right. The maximum value image.Width is never reached by x, so the red component never reach 256.
48	48
49	49		### Run the program
50	50
51	51		You should see a form with a gradient where corners are black, red, yellow and green. When you resize the form, the gradient is resized accordingly.
52	52
53		-	~~<figure>~~
54		-	~~<img src="BGRATutorial4.png" title="BGRATutorial4.png" />~~
55		-	~~<figcaption>BGRATutorial4.png</figcaption>~~
56		-	~~</figure>~~
	53	+	![](/wiki-images/8/8b/BGRATutorial4.png)
57	54
58	55		## Using HSLA colorspace
59	56
60	57		You can use hue, saturation, and lightness. To do this, declare a [[BGRABitmap Pixel types\|THSLAPixel]]. It's values range from 0 to 65535. To convert it to standard RGB pixel, use HSLAToBGRA.
61	58
62	59		``` pascal
63	60		procedure TForm1.FormPaint(Sender: TObject);
64	61		var x,y: integer;
65	62		p: PBGRAPixel;
66	63		image: TBGRABitmap;
67	64		hsla: THSLAPixel;
68	65		begin
69	66		image := TBGRABitmap.Create(ClientWidth,ClientHeight);
70	67		hsla.lightness := 32768;
71	68		hsla.alpha := 65535;
72	69		for y := 0 to image.Height-1 do
73	70		begin
74	71		p := image.Scanline[y];
75	72		hsla.saturation := y*65536 div image.Height;
76	73		for x := 0 to image.Width-1 do
77	74		begin
78	75		hsla.hue := x*65536 div image.Width;
79	76		p^:= HSLAToBGRA(hsla);
80	77		inc(p);
81	78		end;
82	79		end;
83	80		image.InvalidateBitmap; // changed by direct access
84	81
85	82		image.Draw(Canvas,0,0,True);
86	83		image.free;
87	84		end;
88	85		```
89	86
90		-	~~<figure>~~
91		-	~~<img src="BGRATutorial4b.png" title="BGRATutorial4b.png" />~~
92		-	~~<figcaption>BGRATutorial4b.png</figcaption>~~
93		-	~~</figure>~~
	87	+	![](/wiki-images/1/1b/BGRATutorial4b.png)
94	88
95	89		#### Color correction
96	90
97	91		HSLA colors have gamma correction, but there are other possible corrections. For example, H means "hue". In the classical version of HSLA model, each range between primary colors (red/green/blue) is represented by 120 degrees, which equals 21845 colors in [[BGRABitmap Pixel types\|THSLAPixel]]. However, we do not perceive the same differences of colors in these different ranges. The functions HtoG and GtoH apply or unapply a correction, where in the G hue, ranges are not of the same size. To get a corrected hue, write:
98	92
99	93		``` pascal
100	94		hsla.hue := GtoH(x*65536 div image.Width);
101	95		```
102	96
103	97		Notice that the range of oranges is wider. Finally, in the HSLA model, the lightness L does not correspond to the perceived lightness. Instead of only correcting the hue, you can use GSBAToBGRA and BGRAToGSBA instead of HLSAToBGRA and BGRAToHSLA. The G here means that the hue is automatically corrected and the B means it's the perceived lightness (sometimes called Brightness) which is taken into account. So you don't need to call GtoH and HtoG explicitely.
104	98
105	99		The code simple becomes:
106	100
107	101		``` pascal
108	102		procedure TForm1.FormPaint(Sender: TObject);
109	103		var x,y: integer;
110	104		p: PBGRAPixel;
111	105		image: TBGRABitmap;
112	106		hsla: THSLAPixel;
113	107		begin
114	108		image := TBGRABitmap.Create(ClientWidth,ClientHeight);
115	109		hsla.lightness := 32768;
116	110		hsla.alpha := 65535;
117	111		for y := 0 to image.Height-1 do
118	112		begin
119	113		p := image.Scanline[y];
120	114		hsla.saturation := y*65536 div image.Height;
121	115		for x := 0 to image.Width-1 do
122	116		begin
123	117		hsla.hue := x*65536 div image.Width;
124	118		p^:= GSBAToBGRA(hsla);
125	119		inc(p);
126	120		end;
127	121		end;
128	122		image.InvalidateBitmap; // changed by direct access
129	123
130	124		image.Draw(Canvas,0,0,True);
131	125		image.free;
132	126		end;
133	127		```
134	128
135	129		Note that the THSLAPixel type is used, whatever the correction of the color model.
136	130
137	131		### Run the program
138	132
139	133		With full color correction, the gradient is more progressive, and looks like what you would obtain with the Lab color model.
140	134
141		-	~~<figure>~~
142		-	~~<img src="BGRATutorial4c.png" title="BGRATutorial4c.png" />~~
143		-	~~<figcaption>BGRATutorial4c.png</figcaption>~~
144		-	~~</figure>~~
	135	+	![](/wiki-images/a/a6/BGRATutorial4c.png)
145	136
146	137		## Using TXYZABitmap
147	138
148	139		Instead of converting directly the values of pixels, it is possible to use a bitmap with another pixel format. Here is how to use the XYZA colorspace.
149	140
150	141		The TXYZA type contains floating point values from 0 to 1. In the example, the Y value (lightness) is set to 0.5 while the X and Z values varies to express different hues.
151	142
152	143		The X and Z channels can be greater than one depending on the illuminant and typically in daylight the Z value for the brightest white is slightly greater than 1. In theory the Y channel can be greater than one as well if it expresses a light source stronger than the illuminant, but that will saturate when rendering it on a screen.
153	144
154	145		Also here the GetCanvasScaleFactor function (value 1 or greater) is used to determine if there is a Retina display for which the coordinates can be double the pixel size. So in this case, we need to prepare a bitmap that is twice as big and in the end draw it zoomed out.
155	146
156	147		To render on screen, the bitmap needs to be drawn on a BGRA bitmap.
157	148
158	149		``` pascal
159	150		uses BGRABitmap, BGRABitmapTypes, XYZABitmap;
160	151
161	152		procedure TForm1.FormPaint(Sender: TObject);
162	153		var x,y: integer;
163	154		image: TBGRABitmap;
164	155		xyzImage: TXYZABitmap;
165	156		p: PXYZA;
166	157		xyz: TXYZA;
167	158		begin
168	159		// create a bitmap with XYZA colorspace
169	160		// and take into account the scale factor (for MacOS)
170	161		xyzImage := TXYZABitmap.Create(round(ClientWidth * GetCanvasScaleFactor),
171	162		round(ClientHeight * GetCanvasScaleFactor));
172	163		xyz.alpha := 1;
173	164		xyz.Y := 0.5;
174	165		for y := 0 to xyzImage.Height-1 do
175	166		begin
176	167		p := xyzImage.Scanline[y];
177	168		xyz.x := 0.35 + y/xyzImage.Height*0.3;
178	169		for x := 0 to xyzImage.Width-1 do
179	170		begin
180	171		xyz.z := 0.15 + x/xyzImage.Width*0.5;
181	172		p^:= xyz;
182	173		inc(p);
183	174		end;
184	175		end;
185	176		xyzImage.InvalidateBitmap; // changed by direct access
186	177
187	178		// draw the XYZA bitmap on a BGRA bitmap for display
188	179		image := TBGRABitmap.Create(xyzImage.Width, xyzImage.Height);
189	180		image.PutImage(0,0, xyzImage, dmSet);
190	181		// stretch (reduce) because of scale factor
191	182		image.Draw(Canvas, rect(0,0,ClientWidth,ClientHeight), True);
192	183		image.free;
193	184		end;
194	185		```
195	186
196		-	~~<figure>~~
197	187		<img src="BGRATutorial4d.png" title="BGRATutorial4d.png" width="392" />
198		-	~~<figcaption>BGRATutorial4d.png</figcaption>~~
199		-	~~</figure>~~
200	188
201	189		[[BGRABitmap tutorial 3\|Previous tutorial (drawing with the mouse)]] \\| [[BGRABitmap tutorial 5\|Next tutorial (layers and masks)]]
202	190
203	191		---
204	192		From the Free Pascal wiki, page "BGRABitmap tutorial 4", as it stood on 2023-01-02 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).
205	193		Category: BGRABitmap
206	194		Category: Graphics

Back to history