BGRABitmap tutorial 4: what changed

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

Title: BGRABitmap tutorial 4

New		Line
1	+	This tutorial shows you how to access directly to pixels. See reference on [[TBGRABitmap class\|direct pixel access]].
2	+
3	+	## Create a new project
4	+
5	+	Create a new project and add a reference to [[BGRABitmap]], the same way as in [[BGRABitmap tutorial\|the first tutorial]].
6	+
7	+	### Add a painting handler
8	+
9	+	With the object inspector, add an OnPaint handler and write:
10	+
11	+	``` pascal
12	+	procedure TForm1.FormPaint(Sender: TObject);
13	+	var
14	+	x, y: integer;
15	+	p: PBGRAPixel;
16	+	image: TBGRABitmap;
17	+	begin
18	+	image := TBGRABitmap.Create(ClientWidth, ClientHeight);
19	+
20	+	for y := 0 to image.Height-1 do
21	+	begin
22	+	p := image.Scanline[y];
23	+	for x := 0 to image.Width-1 do
24	+	begin
25	+	p^.red := x * 256 div image.Width;
26	+	p^.green := y * 256 div image.Height;
27	+	p^.blue := 0;
28	+	p^.alpha := 255;
29	+	inc(p);
30	+	end;
31	+	end;
32	+	image.InvalidateBitmap; // changed by direct access
33	+
34	+	image.Draw(Canvas, 0, 0, True);
35	+	image.free;
36	+	end;
37	+	```
38	+
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	+
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	+
43	+	``` pascal
44	+	p^.red := x*256 div image.Width;
45	+	```
46	+
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	+
49	+	### Run the program
50	+
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	+
53	+	<figure>
54	+	<img src="BGRATutorial4.png" title="BGRATutorial4.png" />
55	+	<figcaption>BGRATutorial4.png</figcaption>
56	+	</figure>
57	+
58	+	## Using HSLA colorspace
59	+
60	+	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	+
62	+	``` pascal
63	+	procedure TForm1.FormPaint(Sender: TObject);
64	+	var x,y: integer;
65	+	p: PBGRAPixel;
66	+	image: TBGRABitmap;
67	+	hsla: THSLAPixel;
68	+	begin
69	+	image := TBGRABitmap.Create(ClientWidth,ClientHeight);
70	+	hsla.lightness := 32768;
71	+	hsla.alpha := 65535;
72	+	for y := 0 to image.Height-1 do
73	+	begin
74	+	p := image.Scanline[y];
75	+	hsla.saturation := y*65536 div image.Height;
76	+	for x := 0 to image.Width-1 do
77	+	begin
78	+	hsla.hue := x*65536 div image.Width;
79	+	p^:= HSLAToBGRA(hsla);
80	+	inc(p);
81	+	end;
82	+	end;
83	+	image.InvalidateBitmap; // changed by direct access
84	+
85	+	image.Draw(Canvas,0,0,True);
86	+	image.free;
87	+	end;
88	+	```
89	+
90	+	<figure>
91	+	<img src="BGRATutorial4b.png" title="BGRATutorial4b.png" />
92	+	<figcaption>BGRATutorial4b.png</figcaption>
93	+	</figure>
94	+
95	+	#### Color correction
96	+
97	+	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	+
99	+	``` pascal
100	+	hsla.hue := GtoH(x*65536 div image.Width);
101	+	```
102	+
103	+	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	+
105	+	The code simple becomes:
106	+
107	+	``` pascal
108	+	procedure TForm1.FormPaint(Sender: TObject);
109	+	var x,y: integer;
110	+	p: PBGRAPixel;
111	+	image: TBGRABitmap;
112	+	hsla: THSLAPixel;
113	+	begin
114	+	image := TBGRABitmap.Create(ClientWidth,ClientHeight);
115	+	hsla.lightness := 32768;
116	+	hsla.alpha := 65535;
117	+	for y := 0 to image.Height-1 do
118	+	begin
119	+	p := image.Scanline[y];
120	+	hsla.saturation := y*65536 div image.Height;
121	+	for x := 0 to image.Width-1 do
122	+	begin
123	+	hsla.hue := x*65536 div image.Width;
124	+	p^:= GSBAToBGRA(hsla);
125	+	inc(p);
126	+	end;
127	+	end;
128	+	image.InvalidateBitmap; // changed by direct access
129	+
130	+	image.Draw(Canvas,0,0,True);
131	+	image.free;
132	+	end;
133	+	```
134	+
135	+	Note that the THSLAPixel type is used, whatever the correction of the color model.
136	+
137	+	### Run the program
138	+
139	+	With full color correction, the gradient is more progressive, and looks like what you would obtain with the Lab color model.
140	+
141	+	<figure>
142	+	<img src="BGRATutorial4c.png" title="BGRATutorial4c.png" />
143	+	<figcaption>BGRATutorial4c.png</figcaption>
144	+	</figure>
145	+
146	+	## Using TXYZABitmap
147	+
148	+	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	+
150	+	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	+
152	+	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	+
154	+	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	+
156	+	To render on screen, the bitmap needs to be drawn on a BGRA bitmap.
157	+
158	+	``` pascal
159	+	uses BGRABitmap, BGRABitmapTypes, XYZABitmap;
160	+
161	+	procedure TForm1.FormPaint(Sender: TObject);
162	+	var x,y: integer;
163	+	image: TBGRABitmap;
164	+	xyzImage: TXYZABitmap;
165	+	p: PXYZA;
166	+	xyz: TXYZA;
167	+	begin
168	+	// create a bitmap with XYZA colorspace
169	+	// and take into account the scale factor (for MacOS)
170	+	xyzImage := TXYZABitmap.Create(round(ClientWidth * GetCanvasScaleFactor),
171	+	round(ClientHeight * GetCanvasScaleFactor));
172	+	xyz.alpha := 1;
173	+	xyz.Y := 0.5;
174	+	for y := 0 to xyzImage.Height-1 do
175	+	begin
176	+	p := xyzImage.Scanline[y];
177	+	xyz.x := 0.35 + y/xyzImage.Height*0.3;
178	+	for x := 0 to xyzImage.Width-1 do
179	+	begin
180	+	xyz.z := 0.15 + x/xyzImage.Width*0.5;
181	+	p^:= xyz;
182	+	inc(p);
183	+	end;
184	+	end;
185	+	xyzImage.InvalidateBitmap; // changed by direct access
186	+
187	+	// draw the XYZA bitmap on a BGRA bitmap for display
188	+	image := TBGRABitmap.Create(xyzImage.Width, xyzImage.Height);
189	+	image.PutImage(0,0, xyzImage, dmSet);
190	+	// stretch (reduce) because of scale factor
191	+	image.Draw(Canvas, rect(0,0,ClientWidth,ClientHeight), True);
192	+	image.free;
193	+	end;
194	+	```
195	+
196	+	<figure>
197	+	<img src="BGRATutorial4d.png" title="BGRATutorial4d.png" width="392" />
198	+	<figcaption>BGRATutorial4d.png</figcaption>
199	+	</figure>
200	+
201	+	[[BGRABitmap tutorial 3\|Previous tutorial (drawing with the mouse)]] \\| [[BGRABitmap tutorial 5\|Next tutorial (layers and masks)]]
202	+
203	+	---
204	+	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	+	Category: BGRABitmap
206	+	Category: Graphics

Back to history