OpenGL Tutorial: what changed

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

Old	New		Line
1	1		## Introduction
2	2
3	3		OpenGL is the premier environment for developing portable, interactive 2D and 3D graphics applications. Since its introduction in 1992, OpenGL has become the industry's most widely used and supported 2D and 3D graphics application programming interface (API), bringing thousands of applications to a wide variety of computer platforms. OpenGL fosters innovation and speeds application development by incorporating a broad set of rendering, texture mapping, special effects, and other powerful visualization functions. Developers can leverage the power of OpenGL across all popular desktop and workstation platforms, ensuring wide application deployment.
4	4
5	5		You can find more information about OpenGL [here](http://www.opengl.org/about/overview/).
6	6
7	7		### GLUT
8	8
9	9		Note: GLUT is deprecated.
10	10
11	11		GLUT (pronounced like the glut in gluttony) is the OpenGL Utility Toolkit, a window system independent toolkit for writing OpenGL programs. It implements a simple windowing application programming interface (API) for OpenGL. GLUT makes it considerably easier to learn about and explore OpenGL programming. GLUT provides a portable API so you can write a single OpenGL program that works across all PC and workstation OS platforms.
12	12
13	13		You can find more information about GLUT [here](http://www.opengl.org/resources/libraries/glut/).
14	14
15	15		Many Operating Systems come with preinstalled GLUT, but if yours does not have one you can easily find it using [Google](http://www.google.com/).
16	16
17	17		Windows binaries can be downloaded from [www.xmission.com](http://www.xmission.com/~nate/glut.html).
18	18
19	19		The GLUT FPC units information is here [[OpenGL]].
20	20
21	21		### GLFW
22	22
23	23		See <http://www.glfw.org/>
24	24
25	25		### LCL
26	26
27	27		The Lazarus Component Library can be used with OpenGL too. Lazarus includes a TOpenGLControl - a LCL control with an OpenGL context. The lazarus package LazOpenGLContext can be found lazarus/components/opengl/lazopenglcontext.lpk. An example can be found in lazarus/examples/openglcontrol/openglcontrol_demo.lpi.
28	28
29	29		### LCL / GLFW / GLUT
30	30
31	31		When should you use GLUT, when LCL?
32	32
33	33		- GLUT is better if you want to draw everything yourself.
34	34		- LCL is better for normal applications. For example a 3D editor needs a few OpenGL windows and the rest is a normal application using normal buttons, comboboxes, windows, modal windows, etc.
35	35
36	36		The OpenGL part is pretty much the same. GLUT needs a dll under windows, where LCL typically runs out of the box, but a LCL executable is bigger.
37	37
38	38		## Code samples
39	39
40	40		### Creating your first LCL program
41	41
42	42		Using LCL is typically the easiest way to access OpenGL with Lazarus. Since GLUT is deprecated, using the LCL is generally a good idea for a new OpenGL Lazarus project. Most of the code samples described below for GLUT are easy to translate into the LCL code, though you will have to find equivalents for the functions with the 'glut' prefix, for example instead of "glutSwapBuffers" we will use the LCL's "SwapBuffers" property to display our rendering. The one great feature that GLUT provides that is hard to do with the LCL is showing text on the screen (see GLUT's "Bitmap Fonts" section below). However, since this is your first LCL program, we will keep it simple by not showing any text.
43	43
44	44		Lazarus comes with a example OpenGL program, you can find it in the folder Lazarus/Examples/openglcontrol. That example demonstrates many powerful features for creating an animated OpenGL image. However, it is also a relatively complicated program. Below is a minimal Lazarus project that mimics some of the features described in the GLUT samples described below. To create this, launch Lazarus and choose Project/NewProject to create a new application. Choose the Project/ProjectInspector menu item, click the 'Add..' button, go to the 'New Requirement' and and the "LazOpenGLContext" package. Next, paste the code below into your 'unit1.pas'. Then, click on your form and in the events tab of the object inspector link the "OnCreate" event to the function "FormCreate". You should now be able to run your new application by choosing the Run/Run menu item.
45	45
46	46		The code creates a new OpenGL panel that fills the form. OpenGL draws a simple triangle in the form. Note that when you run the application you can resize the form and the triangle rescales proportionally to fill the form.
47	47
48	48		``` pascal
49	49		unit Unit1;
50	50
51	51		{$mode objfpc}{$H+}
52	52
53	53		interface
54	54
55	55		uses
56	56		Classes, SysUtils, FileUtil, Forms, Controls, Graphics, Dialogs, OpenGLContext, gl;
57	57
58	58		type
59	59		TForm1 = class(TForm)
60	60		procedure FormCreate(Sender: TObject);
61	61		procedure GLboxPaint(Sender: TObject);
62	62		private
63	63		GLBox: TOpenGLControl;
64	64		public
65	65		end;
66	66
67	67		var
68	68		Form1: TForm1;
69	69
70	70		implementation
71	71
72	72		{$R *.lfm}
73	73
74	74		procedure TForm1.GLboxPaint(Sender: TObject);
75	75		begin
76	76		glClearColor(0.27, 0.53, 0.71, 1.0); // Set blue background
77	77		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
78	78		glLoadIdentity;
79	79		glBegin(GL_TRIANGLES);
80	80		glColor3f(1, 0, 0);
81	81		glVertex3f( 0.0, 1.0, 0.0);
82	82		glColor3f(0, 1, 0);
83	83		glVertex3f(-1.0,-1.0, 0.0);
84	84		glColor3f(0, 0, 1);
85	85		glVertex3f( 1.0,-1.0, 0.0);
86	86		glEnd;
87	87		GLbox.SwapBuffers;
88	88		end;
89	89
90	90		procedure TForm1.FormCreate(Sender: TObject);
91	91		begin
92	92		GLbox := TOpenGLControl.Create(Self);
93	93		GLbox.AutoResizeViewport := true;
94	94		GLBox.Parent := Self;
95	95		GLBox.MultiSampling := 4;
96	96		GLBox.Align := alClient;
97	97		GLBox.OnPaint := @GLboxPaint; // for "mode delphi" this would be "GLBox.OnPaint := GLboxPaint"
98	98		GLBox.invalidate;
99	99		end;
100	100
101	101		end.
102	102		```
103	103
104	104		### Creating your first GLUT program
105	105
106	106		In order to use GLUT, you must first include unit glut and then initialize it. This is done using glutInit function. This function can parse the command line and set parameters for the main window, but it expects input in C/C++ style. You'll have to write your own function to make the conversion from ParamCount and ParamStr to C/C++ like command line parameters.
107	107
108	108		``` pascal
109	109		procedure glutInitPascal(ParseCmdLine: Boolean);
110	110		var
111	111		Cmd: array of PChar;
112	112		CmdCount, I: Integer;
113	113		begin
114	114		if ParseCmdLine then
115	115		CmdCount := ParamCount + 1
116	116		else
117	117		CmdCount := 1;
118	118		SetLength(Cmd, CmdCount);
119	119		for I := 0 to CmdCount - 1 do
120	120		Cmd[I] := PChar(ParamStr(I));
121	121		glutInit(@CmdCount, @Cmd);
122	122		end;
123	123		```
124	124
125	125		In essence, you create an array and fill it with strings from ParamStr. This function also takes a parameter that can control what is passed to glutInit -- either the whole command line or just the executable file name.
126	126
127	127		ToDo: probably glutInit(@argc, @argv); is enough.
128	128
129	129		More about glutInit: <http://www.opengl.org/resources/libraries/glut/spec3/node10.html>
130	130
131	131		Next, you need to create a main window. Set the display mode for the main window using glutInitDisplayMode. It only takes one parameter which is a combination of flags. Usually GLUT_DOUBLE or GLUT_RGB or GLUT_DEPTH is all you will need.
132	132
133	133		More about glutInitDisplayMode: <http://www.opengl.org/resources/libraries/glut/spec3/node12.html>
134	134
135	135		The position and size of the window is controlled using glutInitWindowPosition and glutInitWindowSize. They take 2 parameters. X and Y coordinates in the former, and width and height in the latter. You can use glutGet to find the screen size and center the window.
136	136
137	137		More about glutInitWindowPosition, glutInitWindowSize and glutGet: <http://www.opengl.org/resources/libraries/glut/spec3/node11.html> <http://www.opengl.org/documentation/specs/glut/spec3/node70.html>
138	138
139	139		Finally, the window should be created using the glutCreateWindow function. It will create the window and set its caption through a parameter. As a result it will return the window's handle. This can be used with other functions that require it.
140	140
141	141		More about glutCreateWindow: <http://www.opengl.org/resources/libraries/glut/spec3/node16.html>
142	142
143	143		Before your program can enter the main loop, you must set some callbacks. You will a need callback for drawing the window, for resizing and for getting keyboard input. These callbacks are set using glutDisplayFunc, glutReshapeFunc and glutKeyboardFunc.
144	144
145	145		More about setting callbacks: <http://www.opengl.org/resources/libraries/glut/spec3/node45.html#SECTION00080000000000000000>
146	146
147	147		Your drawing function might look like this:
148	148
149	149		``` pascal
150	150		procedure DrawGLScene; cdecl;
151	151		begin
152	152		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
153	153		glutSwapBuffers;
154	154		end;
155	155		```
156	156
157	157		This will only clear the window to the background color and reset the zbuffer (don't worry about zbuffer... more about that later).
158	158
159	159		Your resize function might look like this:
160	160
161	161		``` pascal
162	162		procedure ReSizeGLScene(Width, Height: Integer); cdecl;
163	163		begin
164	164		if Height = 0 then
165	165		Height := 1;
166	166
167	167		glViewport(0, 0, Width, Height);
168	168		glMatrixMode(GL_PROJECTION);
169	169		glLoadIdentity;
170	170		gluPerspective(45, Width / Height, 0.1, 1000);
171	171
172	172		glMatrixMode(GL_MODELVIEW);
173	173		glLoadIdentity;
174	174		end;
175	175		```
176	176
177	177		With this code, you tell OpenGL where in the window it should draw and set matrices to the desired values (matrix functions will be explained later).
178	178
179	179		Keyboard input is evaluated with the following callback:
180	180
181	181		``` pascal
182	182		procedure GLKeyboard(Key: Byte; X, Y: Longint); cdecl;
183	183		begin
184	184		if Key = 27 then
185	185		Halt(0);
186	186		end;
187	187		```
188	188
189	189		This function will instruct your program to exit if you press ESC key. GLUT is event driven and the only way to terminate your program is to call Halt inside one of your callback functions. If you close the window in some other way, it will disappear, but the program will continue to loop through the main routine indefinitely.
190	190
191	191		To start the main loop, call glutMainLoop. It will enter a loop that never ends, which calls all your callback functions.
192	192
193	193		The main part of your program might look like this:
194	194
195	195		``` pascal
196	196		const
197	197		AppWidth = 640;
198	198		AppHeight = 480;
199	199
200	200		procedure InitializeGL;
201	201		begin
202	202		glClearColor(0.18, 0.20, 0.66, 0);
203	203		end;
204	204
205	205		var
206	206		ScreenWidth, ScreenHeight: Integer;
207	207		begin
208	208		glutInitPascal(True);
209	209		glutInitDisplayMode(GLUT_DOUBLE or GLUT_RGB or GLUT_DEPTH);
210	210		glutInitWindowSize(AppWidth, AppHeight);
211	211		ScreenWidth := glutGet(GLUT_SCREEN_WIDTH);
212	212		ScreenHeight := glutGet(GLUT_SCREEN_HEIGHT);
213	213		glutInitWindowPosition((ScreenWidth - AppWidth) div 2,
214	214		(ScreenHeight - AppHeight) div 2);
215	215		glutCreateWindow('OpenGL Tutorial 1');
216	216
217	217		InitializeGL;
218	218
219	219		glutDisplayFunc(@DrawGLScene);
220	220		glutReshapeFunc(@ReSizeGLScene);
221	221		glutKeyboardFunc(@GLKeyboard);
222	222
223	223		glutMainLoop;
224	224		end.
225	225		```
226	226
227	227		The next tutorial will add some code that will draw a simple shape.
228	228
229	229		Download source code or a linux/windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
230	230
231	231		### Drawing a simple shape
232	232
233	233		Note: The following parts are almost only OpenGL, so they run under GLUT and LCL. You can recognize GLUT specific functions with the prefix 'glu'.
234	234
235	235		This time we shall add just a few lines of code and focus on explanation of some of the OpenGL functions.
236	236
237	237		Let us explain code you already have.
238	238
239	239		``` pascal
240	240		...
241	241		glMatrixMode(GL_PROJECTION);
242	242		glLoadIdentity;
243	243		gluPerspective(45, Width / Height, 0.1, 1000);
244	244
245	245		glMatrixMode(GL_MODELVIEW);
246	246		glLoadIdentity;
247	247		end;
248	248		```
249	249
250	250		Using glMatrixMode function you chose which matrix you want to change. OpenGL works with 3 matrices: GL_MODELVIEW: this one is used to move vertex to model space. GL_PROJECTION: this one is used to convert 3d coordinate to 2d coordinate for finall pixel position. GL_TEXTURE: this one is used to alter texture coordinates.
251	251
252	252		Once you chose matrix you want to change, you can call functions that affect matrix values. glLoadIdentity will reset matrix so it doesn't affect vertex position. Since almost all matrix functions multiply current matrix with a generated one, you sometimes need to clear matrix with this function.
253	253
254	254		In order to set perspective matrix, you can use gluPerspective function. Four parameters present the field of view, aspect ratio, near and far plane. It's that simple.
255	255
256	256		Now, you'll change model matrix... for this time, you just set it to identity.
257	257
258	258		OK... and now, the code for drawing the first shape:
259	259
260	260		``` pascal
261	261		procedure DrawGLScene; cdecl;
262	262		begin
263	263		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
264	264
265	265		glLoadIdentity;
266	266		glTranslatef(0, 0, -5);
267	267
268	268		glBegin(GL_TRIANGLES);
269	269		glColor3f(1, 0, 0);
270	270		glVertex3f(-1, -1, 0);
271	271
272	272		glColor3f(0, 1, 0);
273	273		glVertex3f(1, -1, 0);
274	274
275	275		glColor3f(0, 0, 1);
276	276		glVertex3f(0, 1, 0);
277	277		glEnd;
278	278
279	279		glutSwapBuffers;
280	280		end;
281	281		```
282	282
283	283		We have allready used glClear function. It will just reset buffers. We'll skip next two functions and head for drawing ones.
284	284
285	285		glBegin marks beginning of drawing block. After this function you can start entering vertices. Parameter describes how are vertices used when drawing:
286	286
287	287		GL_POINTS: Treats each vertex as a single point. Vertex n defines point n. N points are drawn.
288	288
289	289		GL_LINES: Treats each pair of vertices as an independent line segment. Vertices 2n-1 and 2n define line n. n/2 lines are drawn.
290	290
291	291		GL_LINE_STRIP: Draws a connected group of line segments from the first vertex to the last. n-1 lines are drawn.
292	292
293	293		GL_LINE_LOOP: Draws a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n+1 define line n. The last line, however, is defined by vertices n and 1. n lines are drawn.
294	294
295	295		GL_TRIANGLES: Treats each triplet of vertices as an independent triangle. Vertices 3n-2, 3n-1 and 3n define triangle n. n/3 triangles are drawn.
296	296
297	297		GL_TRIANGLE_STRIP: Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n+1 and n+2 define triangle n. For even n, vertices n+1, n and n+2 define triangle n. n-2 triangles are drawn.
298	298
299	299		GL_TRIANGLE_FAN: Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1. n+1 and n+2 define triangle n. n-2 triangles are drawn.
300	300
301	301		GL_QUADS: Treats each group of four vertices as an independent quadrilateral. Vertices 4n-3, 4n-2, 4n-1 and 4n define quadrilateral n. n/4 quadrilaterals are drawn.
302	302
303	303		GL_QUAD_STRIP: Draws a connected group of quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n-1, 2n, 2n+2 and 2n+1 define quadrilateral n. n/2-1 quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data.
304	304
305	305		GL_POLYGON: Draws a single, convex polygon. Vertices 1 through n define this polygon.
306	306
307	307		![](/wiki-images/f/f3/SimpleShapePic1.jpg) You'll draw single triangle and for that GL_TRIANGLES flag will do the trick. glVertex3f function defines the position of a vertex you want to draw. There are more glVertex* functions. Only difference is number and type of parameters they take. For instance... glVertex2i takes two parameters (x and y) of integer type. glVertex3f will almost always be just what you need.
308	308
309	309		Before glVertex you can set color, material, texture... For simplicity you'll just specify color for each vertex in this tutorial. Color is set using glColor3f function. glColor can also take different set of parameters like glVertex.
310	310
311	311		As we look through code we can see that Z is set to 0 for all vertices. Since you set near plane to 0.1, triangle will not be visible. That is where those two functions we skipped in the beginning jump in. We already know that glLoadIdentity reset matrix. glTranslatef moves triangles by X, Y and Z values you provide. Since you set Z to -5 (negative Z is farther from camera) all vertices will be drawn 5 units far from point of view and will be visible.
312	312
313	313		In the end you call glEnd functions that finishes drawing. You could now start another drawing block with new glBegin function if you wish.
314	314
315	315		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
316	316
317	317		### Using display lists
318	318
319	319		Sometimes you'll need to draw some object multiple times on scene. OpenGL has ability to build display lists which make drawing a bit faster. Creating display list is very easy... just draw vertices as you did in previous tutorial and enclose them with glNewList and glEndList calls.
320	320
321	321		``` pascal
322	322		const
323	323		LIST_OBJECT = 1;
324	324
325	325		procedure CreateList;
326	326		begin
327	327		glNewList(LIST_OBJECT, GL_COMPILE);
328	328		glBegin(GL_TRIANGLE_FAN);
329	329		glColor3f(1, 0, 0);
330	330		glVertex3f(0, 0.5, 0);
331	331
332	332		glColor3f(1, 1, 0);
333	333		glVertex3f(-0.5, -0.5, 0.5);
334	334
335	335		glColor3f(1, 1, 1);
336	336		glVertex3f(0.5, -0.5, 0.5);
337	337
338	338		glColor3f(0, 1, 1);
339	339		glVertex3f(0.5, -0.5, -0.5);
340	340
341	341		glColor3f(0, 0, 1);
342	342		glVertex3f(-0.5, -0.5, -0.5);
343	343
344	344		glColor3f(0, 1, 0);
345	345		glVertex3f(-0.5, -0.5, 0.5);
346	346		glEnd;
347	347
348	348		glBegin(GL_QUADS);
349	349		glColor3f(1, 1, 0);
350	350		glVertex3f(-0.5, -0.5, 0.5);
351	351
352	352		glColor3f(1, 1, 1);
353	353		glVertex3f(0.5, -0.5, 0.5);
354	354
355	355		glColor3f(0, 1, 1);
356	356		glVertex3f(0.5, -0.5, -0.5);
357	357
358	358		glColor3f(0, 0, 1);
359	359		glVertex3f(-0.5, -0.5, -0.5);
360	360
361	361		glColor3f(0, 1, 0);
362	362		glVertex3f(-0.5, -0.5, 0.5);
363	363		glEnd;
364	364		glEndList;
365	365		end;
366	366		```
367	367
368	368		glNewList creates new display list and all drawing functions will be recorded until glEndList is called. The first parameter for glNewList function is list ID. Every list is defined by it's ID. If list with given ID is already created it fill be cleared before recording. If the second parameter is GL_COMPILE then all drawing functions are just recorded, but if it is GL_COMPILE_AND_EXECUTE then they are recorded and executed automatically.
369	369
370	370		glIsList function can help you with display lists. It can tell if some list ID is already filled with data. Another useful function is glGenLists. It will create multiple empty display lists. You pass number of display lists you need and you get ID of the first one. If you require n lists, and get r ID, generated display lists are: r, r+1, r+2,..., r+n-1
371	371
372	372		All created lists should be deleted. You will do that before program exits:
373	373
374	374		``` pascal
375	375		procedure GLKeyboard(Key: Byte; X, Y: Longint); cdecl;
376	376		begin
377	377		if Key = 27 then
378	378		begin
379	379		glDeleteLists(LIST_OBJECT, 1);
380	380		Halt(0);
381	381		end;
382	382		end;
383	383		```
384	384
385	385		glDeleteLists takes 2 parameters, ID of display list and number of lists to delete. If ID is r, and number of lists to delete is n, deleted lists are: r, r+1, r+2,..., r+n-1
386	386
387	387		Now you know how to create and delete display lists... let's see how to draw them:
388	388
389	389		``` pascal
390	390		procedure DrawGLScene; cdecl;
391	391		begin
392	392		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
393	393
394	394		glLoadIdentity;
395	395		glTranslatef(-2, 0, -5);
396	396		glRotatef(40, 1, 0, 1);
397	397		glCallList(LIST_OBJECT);
398	398
399	399		glLoadIdentity;
400	400		glTranslatef(1, -2, -10);
401	401		glRotatef(62, 0, 1, 0);
402	402		glCallList(LIST_OBJECT);
403	403
404	404		glLoadIdentity;
405	405		glTranslatef(-4, 0.5, -15);
406	406		glRotatef(200, 1, 0, 0);
407	407		glCallList(LIST_OBJECT);
408	408
409	409		glutSwapBuffers;
410	410		end;
411	411		```
412	412
413	413		![](/wiki-images/a/a5/DisplayListsPic1.jpg) Using glCallList you can draw only one display list. In this tutorial, before drawing display list, you change model matrix and draw object in different places. Some times you would like to draw multiple lists at once. That is possible using glCallLists function. It takes number of lists you want to draw, type of array that contains display list IDs and array with display list IDs. Type of list can be one of the following:
414	414
415	415		GL_BYTE: list is treated as an array of signed bytes, each in the range -128 through 127.
416	416
417	417		GL_UNSIGNED_BYTE: list is treated as an array of unsigned bytes, each in the range 0 through 255.
418	418
419	419		GL_SHORT: list is treated as an array of signed two-byte integers, each in the range -32768 through 32767.
420	420
421	421		GL_UNSIGNED_SHORT: list is treated as an array of unsigned two-byte integers, each in the range 0 through 65535.
422	422
423	423		GL_INT: lists is treated as an array of signed four-byte integers.
424	424
425	425		GL_UNSIGNED_INT: list is treated as an array of unsigned four-byte integers.
426	426
427	427		GL_FLOAT: list is treated as an array of four-byte floating-point values.
428	428
429	429		GL_2_BYTES: list is treated as an array of unsigned bytes. Each pair of bytes specifies a single display list ID. The value of the pair is computed as 256 times the unsigned value of the first byte plus the unsigned value of the second byte.
430	430
431	431		GL_3_BYTES: list is treated as an array of unsigned bytes. Each triplet of bytes specifies a single display list ID. The value of the triplet is computed as 65536 times the unsigned value of the first byte, plus 256 times the unsigned value of the second byte, plus the unsigned value of the third byte.
432	432
433	433		GL_4_BYTES: list is treated as an array of unsigned bytes. Each quadruplet of bytes specifies a single display list ID. The value of the quadruplet is computed as 16777216 times the unsigned value of the first byte, plus 65536 times the unsigned value of the second byte, plus 256 times the unsigned value of the third byte, plus the unsigned value of the fourth byte.
434	434
435	435		That is for now. Next tutorial will show how to create little planetary system. We'll talk about matrices and how to make animated scene that doesn't depend of number of frames per second.
436	436
437	437		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
438	438
439	439		### Full screen animation
440	440
441	441		Entering full screen mode is easy with GLUT. Let's change main part of the program:
442	442
443	443		``` pascal
444	444		const
445	445		FSMode = '800x600:32@75';
446	446
447	447		begin
448	448		glutInitPascal(False);
449	449		glutInitDisplayMode(GLUT_DOUBLE or GLUT_RGB or GLUT_DEPTH);
450	450		glutGameModeString(FSMode);
451	451		glutEnterGameMode;
452	452		glutSetCursor(GLUT_CURSOR_NONE);
453	453
454	454		InitializeGL;
455	455
456	456		glutDisplayFunc(@DrawGLScene);
457	457		glutReshapeFunc(@ReSizeGLScene);
458	458		glutKeyboardFunc(@GLKeyboard);
459	459		glutIdleFunc(@DrawGLScene);
460	460
461	461		glutMainLoop;
462	462		end.
463	463		```
464	464
465	465		Since we don't want GLUT to parse command line this time we call glutInitPascal with False parameter. As you can see, there is no code for window creation. GLUT have glutEnterGameMode that create full screen window. To specify what kind of full screen mode you want, you call glutGameModeString function which takes string that defines mode you like. Format of that string is:
466	466
467		-	~~`[width "x" height][":" bpp]["@" hertz]`~~
	467	+	```text
	468	+	[width "x" height][":" bpp]["@" hertz]
	469	+	```
468	470
469	471		In FSMode string we declared that full screen mode should be 800x600, with 32bit pallete and 75Hz refresh. It is possible to skip one of the group. If you omit size, GLUT will try to use current one or first smaller that can work. That policy is used and for other parameters.
470	472
471	473		Usually in full screen mode cursor is not visible. To hide cursor you use glutSetCursor function. It takes only one parameter which describes cursor you would like to see:
472	474
473		-	~~`GLUT_CURSOR_RIGHT_ARROW`\~~
474		-	~~`GLUT_CURSOR_LEFT_ARROW`\~~
475		-	~~`GLUT_CURSOR_INFO`\~~
476		-	~~`GLUT_CURSOR_DESTROY`\~~
477		-	~~`GLUT_CURSOR_HELP`\~~
478		-	~~`GLUT_CURSOR_CYCLE`\~~
479		-	~~`GLUT_CURSOR_SPRAY`\~~
480		-	~~`GLUT_CURSOR_WAIT`\~~
481		-	~~`GLUT_CURSOR_TEXT`\~~
482		-	~~`GLUT_CURSOR_CROSSHAIR`\~~
483		-	~~`GLUT_CURSOR_UP_DOWN`\~~
484		-	~~`GLUT_CURSOR_LEFT_RIGHT`\~~
485		-	~~`GLUT_CURSOR_TOP_SIDE`\~~
486		-	~~`GLUT_CURSOR_BOTTOM_SIDE`\~~
487		-	~~`GLUT_CURSOR_LEFT_SIDE`\~~
488		-	~~`GLUT_CURSOR_RIGHT_SIDE`\~~
489		-	~~`GLUT_CURSOR_TOP_LEFT_CORNER`\~~
490		-	~~`GLUT_CURSOR_TOP_RIGHT_CORNER`\~~
491		-	~~`GLUT_CURSOR_BOTTOM_RIGHT_CORNER`\~~
492		-	~~`GLUT_CURSOR_BOTTOM_LEFT_CORNER`\~~
493		-	~~`GLUT_CURSOR_FULL_CROSSHAIR`\~~
494		-	~~`GLUT_CURSOR_NONE`\~~
495		-	~~`GLUT_CURSOR_INHERIT`~~
	475	+	```text
	476	+	GLUT_CURSOR_RIGHT_ARROW
	477	+	GLUT_CURSOR_LEFT_ARROW
	478	+	GLUT_CURSOR_INFO
	479	+	GLUT_CURSOR_DESTROY
	480	+	GLUT_CURSOR_HELP
	481	+	GLUT_CURSOR_CYCLE
	482	+	GLUT_CURSOR_SPRAY
	483	+	GLUT_CURSOR_WAIT
	484	+	GLUT_CURSOR_TEXT
	485	+	GLUT_CURSOR_CROSSHAIR
	486	+	GLUT_CURSOR_UP_DOWN
	487	+	GLUT_CURSOR_LEFT_RIGHT
	488	+	GLUT_CURSOR_TOP_SIDE
	489	+	GLUT_CURSOR_BOTTOM_SIDE
	490	+	GLUT_CURSOR_LEFT_SIDE
	491	+	GLUT_CURSOR_RIGHT_SIDE
	492	+	GLUT_CURSOR_TOP_LEFT_CORNER
	493	+	GLUT_CURSOR_TOP_RIGHT_CORNER
	494	+	GLUT_CURSOR_BOTTOM_RIGHT_CORNER
	495	+	GLUT_CURSOR_BOTTOM_LEFT_CORNER
	496	+	GLUT_CURSOR_FULL_CROSSHAIR
	497	+	GLUT_CURSOR_NONE
	498	+	GLUT_CURSOR_INHERIT
	499	+	```
496	500
497	501		glutIdleFunc defines callback function that you want to be called every time you program has no messages to process. Since we just want to render new frame if there is nothing to do, just set idle function to DrawGLScene. Some other tutorials show that idle function should send refresh message insted of drawing, but that way I have 50-100 frames less than using method I described.
498	502
499	503		Now, let's look at the program termination where you need to exit full screen mode:
500	504
501	505		``` pascal
502	506		procedure GLKeyboard(Key: Byte; X, Y: Longint); cdecl;
503	507		begin
504	508		if Key = 27 then
505	509		begin
506	510		glutLeaveGameMode;
507	511		Halt(0);
508	512		end;
509	513		end;
510	514		```
511	515
512	516		As you can see, all you need to do is to call glutLeaveGameMode.
513	517
514	518		Now, we'll introduce some new matrix functions. First, let's change ReSizeGLScene function:
515	519
516	520		``` pascal
517	521		procedure ReSizeGLScene(Width, Height: Integer); cdecl;
518	522		begin
519	523		...
520	524		glMatrixMode(GL_MODELVIEW);
521	525		glLoadIdentity;
522	526		gluLookAt(0, 20, 25, 0, 0, 0, 0, 1, 0);
523	527		end;
524	528		```
525	529
526	530		gluLookAt create matrix that will define from where are you look to objects. First 3 parameters are X, Y and Z coordinate of position of camera. Next 3 parameters are X, Y and Z coordinate of point where camera look at, and last 3 parameters defines "up" vector (where is "up" for the camera). Usually, up is positive y axis.
527	531
528	532		OK, let's draw now. Since you set matrix with gluLookAt that should be used with all objects, you can't just use glLoadIdentity to reset matrix for next object... you'll save previous matrix state and restore it after object is drawn:
529	533
530	534		``` pascal
531	535		procedure DrawGLScene; cdecl;
532	536		var
533	537		T: Single;
534	538		begin
535	539		T := glutGet(GLUT_ELAPSED_TIME) / 1000;
536	540		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
537	541
538	542		glPushMatrix;
539	543		glRotatef(5 * T, 0, 1, 0);
540	544		glColor3f(1, 1, 0);
541	545		glutWireSphere(2, 20, 20);
542	546		glPopMatrix;
543	547
544	548		glPushMatrix;
545	549		glRotatef(90 * T, 0, 1, 0);
546	550		glTranslatef(5, 0, 0);
547	551		glRotatef(40 * T, 0, 1, 0);
548	552		glColor3f(1, 0, 0);
549	553		glutWireSphere(0.6, 10, 10);
550	554		glPopMatrix;
551	555
552	556		glPushMatrix;
553	557		glRotatef(60 * T, 0, 1, 0);
554	558		glTranslatef(-3, 0, 9);
555	559		glRotatef(50 * T, 0, 1, 0);
556	560		glColor3f(0, 1, 0);
557	561		glutWireSphere(1, 16, 16);
558	562
559	563		glPushMatrix;
560	564		glRotatef(360 * T, 0, 1, 0);
561	565		glTranslatef(-1.7, 0, 0);
562	566		glRotatef(50 * T, 0, 1, 0);
563	567		glColor3f(0, 0, 1);
564	568		glutWireSphere(0.4, 10, 10);
565	569		glPopMatrix;
566	570
567	571		glPopMatrix;
568	572
569	573		glutSwapBuffers;
570	574		end;
571	575		```
572	576
573	577		![](/wiki-images/5/51/FullScreenAnimationPic1.jpg) glPushMatrix i glPopMatrix are used to save and restore matrix state. As you can see, we save matrix state, then change matrix in order to draw object in right place, and then restore old matrix state.
574	578
575	579		You may wonder what is T variable for. Well, it is used to determen animation speed. Every change that depends on time is multiplied with T. That way animation speed is constant on every frame rate. glutGet function with GLUT_ELAPSED_TIME parameter returns time in milliseconds from glutInit is called. By dividing that value with 1000, we get time in seconds.
576	580
577	581		glRotatef function create rotation matrix. First parameter is angle in degrees, and last 3 parameters defines axis around which rotation will be done. Since you multiplied angle with T, object will be rotated by that angle in exactly 1 second.
578	582
579	583		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
580	584
581	585		### Light
582	586
583	587		This tutorial will introduce some light to the scene. You'll make rotating cube and one light which will add some realism to the scene, but first let's make some utility unit.
584	588
585	589		For now it will have only basic functions to help us getting current and delta (time that elapsed from one render to other render call) times and for calculating frames per second.
586	590
587	591		``` pascal
588	592		unit utils;
589	593
590	594		{$mode objfpc}{$H+}
591	595
592	596		interface
593	597
594	598		uses
595	599		glut;
596	600
597	601		function GetTotalTime: Single;
598	602		function GetDeltaTime: Single;
599	603		procedure FrameRendered(Count: Integer = 1);
600	604		function GetFPS: Single;
601	605
602	606		implementation
603	607
604	608		var
605	609		OldTime: Integer = 0;
606	610		FPSTime: Integer = 0;
607	611		FPSCount: Integer = 0;
608	612
609	613		function GetTotalTime: Single;
610	614		begin
611	615		Result := glutGet(GLUT_ELAPSED_TIME) / 1000;
612	616		end;
613	617
614	618		function GetDeltaTime: Single;
615	619		var
616	620		NewTime: Integer;
617	621		begin
618	622		NewTime := glutGet(GLUT_ELAPSED_TIME);
619	623		Result := (NewTime - OldTime) / 1000;
620	624		OldTime := NewTime;
621	625		end;
622	626
623	627		procedure FrameRendered(Count: Integer);
624	628		begin
625	629		Inc(FPSCount, Count);
626	630		end;
627	631
628	632		function GetFPS: Single;
629	633		var
630	634		NewTime: Integer;
631	635		begin
632	636		NewTime := glutGet(GLUT_ELAPSED_TIME);
633	637
634	638		Result := FPSCount / ((NewTime - FPSTime) / 1000);
635	639
636	640		FPSTime := NewTime;
637	641		FPSCount := 0;
638	642		end;
639	643
640	644		end.
641	645		```
642	646
643	647		As you can see, there is nothing complicated in this unit. Time is simply saved betwen calls and difference is returned. FrameRendered should be called every time you draw scene so function can calculate FPS.
644	648
645	649		Now, let's have fun with lights.
646	650
647	651		OpenGL have several types of light... ambient, diffuse, point, spot, specular and emissive light.
648	652
649	653		Ambient light is something like Sun. When sun rays pass through the window of a room they hit the walls and are reflected and scattered into all different directions which averagely brightens up the whole room. All vertices are lit with ambient light.
650	654
651	655		Diffuse light can be represented as parallel light rays comming from far away. They will lit only vertices that are oriented towards the light source.
652	656
653	657		Point light lights all around it. It is like a fire ball, it send light rays all around it and lights vertices that are oriented towards light source and that are close enough.
654	658
655	659		Spot light is like light from flashlight. It is simply a point light source with a small light cone radius. All vertices that falls inside of cone and are close enough are lit.
656	660
657	661		Just like Diffuse light, Specular light is a directional type of light. It comes from one particular direction. The difference between the two is that specular light reflects off the surface in a sharp and uniform way. The rendering of specular light relies on the angle between the viewer and the light source. From the viewer’s standpoint specular light creates a highlighted area on the surface of the viewed object known as specular highlight or specular reflection.
658	662
659	663		Emissive light is a little different than any other previously explained light components. This light comes out of object you draw but don't lit other objects in nearby.
660	664
661	665		For simplicity we'll use only diffuse light in this tutorial. Later on, some other lights may appear in tutorials :)
662	666
663	667		Let's see how to enable light in scene:
664	668
665	669		``` pascal
666	670		const
667	671		DiffuseLight: array[0..3] of GLfloat = (0.8, 0.8, 0.8, 1);
668	672
669	673		glEnable(GL_LIGHTING);
670	674		glLightfv(GL_LIGHT0, GL_DIFFUSE, DiffuseLight);
671	675		glEnable(GL_LIGHT0);
672	676		```
673	677
674	678		As you see, we enable lighting in OpenGL so lights affect scene you are rendering. Light parameters are set with glLightfv function. It takes 3 parameters... one for light number you want to change (OpenGL suports up to 8 lights), next tells OpenGL what light parameter to change, and the last one is new parameter for light. You'll set just diffuse color for light in this tutorial. After that, you can enable light and there will be light in the scene... but... that is not all.
675	679
676	680		More about glLightfv: <http://www.opengl.org//documentation/specs/man_pages/hardcopy/GL/html/gl/light.html>
677	681
678	682		If you want to use lights you can't just set color for vertex... you must set material for vertices. Let's setup material for drawing:
679	683
680	684		``` pascal
681	685		glEnable(GL_COLOR_MATERIAL);
682	686		glColorMaterial(GL_FRONT, GL_AMBIENT_AND_DIFFUSE);
683	687		```
684	688
685	689		![](/wiki-images/e/ed/LightPic1.jpg) You expected something more complicated, do you? :) Well, this code allows us to use glColor function to set material to vertices. By using glEnable function and GL_COLOR_MATERIAL flag, you can define what material properties will glColor change. glColorMaterial(GL_FRONT, GL_AMBIENT_AND_DIFFUSE) tells OpenGL that glColor changes ambient and diffuse material. We'll discus materials more in later tutorials.
686	690
687	691		One more thing that is important when using lights... every vertex must have normal associated with it. Normal is used to find the direction of vertex so light can be calculated properly. You'll use GLUT function to draw cube and it provides normals for us, so this time we'll just walk by normals.
688	692
689	693		After all those setting ups, light will shine up your cube :)
690	694
691	695		Part of the text is copied from [The OpenGL Light Bible](http://www.falloutsoftware.com/tutorials/gl/gl8.htm)
692	696
693	697		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
694	698
695	699		### Bitmap fonts
696	700
697	701		Games and programs usually need to write some text on screen. GLUT provides several functions for drawing chars that are platform independent.
698	702
699	703		First, we'll show how to use default bitmap fonts. Almost all code additions will be made to utils.pas unit.
700	704
701	705		Since text will be drawn in 2D, we'll need to know width and height of viewport... so, we'll write two functions for that:
702	706
703	707		``` pascal
704	708		function glGetViewportWidth: Integer;
705	709		var
706	710		Rect: array[0..3] of Integer;
707	711		begin
708	712		glGetIntegerv(GL_VIEWPORT, @Rect);
709	713		Result := Rect[2] - Rect[0];
710	714		end;
711	715
712	716		function glGetViewportHeight: Integer;
713	717		var
714	718		Rect: array[0..3] of Integer;
715	719		begin
716	720		glGetIntegerv(GL_VIEWPORT, @Rect);
717	721		Result := Rect[3] - Rect[1];
718	722		end;
719	723		```
720	724
721	725		We just get left/right, top/bottom and calculate width/height by subtracting them.
722	726
723	727		There must be functions for entering and leaving 2D mode:
724	728
725	729		``` pascal
726	730		procedure glEnter2D;
727	731		begin
728	732		glMatrixMode(GL_PROJECTION);
729	733		glPushMatrix;
730	734		glLoadIdentity;
731	735		gluOrtho2D(0, glGetViewportWidth, 0, glGetViewportHeight);
732	736
733	737		glMatrixMode(GL_MODELVIEW);
734	738		glPushMatrix;
735	739		glLoadIdentity;
736	740
737	741		glDisable(GL_DEPTH_TEST);
738	742		end;
739	743
740	744		procedure glLeave2D;
741	745		begin
742	746		glMatrixMode(GL_PROJECTION);
743	747		glPopMatrix;
744	748		glMatrixMode(GL_MODELVIEW);
745	749		glPopMatrix;
746	750
747	751		glEnable(GL_DEPTH_TEST);
748	752		end;
749	753		```
750	754
751	755		When entering 2D mode, we save current matrices and set 2D matrix using gluOrtho2D function. This way if we draw some thing on 100, 100 it will be drawn on exactly 100 pixels from left edge of window, and 100 pixels form bottom edge (positive Y is up). Also, we disable ZBuffer. This way text won't alter ZBuffer.
752	756
753	757		Leaving 2D mode just returns old matrices and enable ZBuffer.
754	758
755	759		Now, we can create function for text drawing:
756	760
757	761		``` pascal
758	762		procedure glWrite(X, Y: GLfloat; Font: Pointer; Text: String);
759	763		var
760	764		I: Integer;
761	765		begin
762	766		glRasterPos2f(X, Y);
763	767		for I := 1 to Length(Text) do
764	768		glutBitmapCharacter(Font, Integer(Text[I]));
765	769		end;
766	770		```
767	771
768	772		glutBitmapCharacter can draw only one character of selected font. First parameter is desired font (GLUT_BITMAP_9_BY_15, GLUT_BITMAP_8_BY_13, GLUT_BITMAP_TIMES_ROMAN_10, GLUT_BITMAP_TIMES_ROMAN_24, GLUT_BITMAP_HELVETICA_10, GLUT_BITMAP_HELVETICA_12 or GLUT_BITMAP_HELVETICA_18) and other one is character.
769	773
770	774		Character will be drawn at current raster position. To set desired raster position we call glRasterPos function. glRasterPos can handle different number and types of parameters just like glVertex function. Coordinate specified is transformed by model and projection matrix to get 2D coordinate where new raster position will be. Since we entered 2D mode, X and Y coordinates are actual 2D coordinates where drawing will occur.
771	775
772	776		This new functions will make text drawing very easy:
773	777
774	778		``` pascal
775	779		procedure DrawGLScene; cdecl;
776	780		begin
777	781		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
778	782
779	783		glLoadIdentity;
780	784		glTranslatef(0, 0, -5);
781	785		glRotatef(GetTotalTime * 10, 0, 0.5, 0.5);
782	786
783	787		glColor3f(1, 0, 0);
784	788		glutSolidCube(2);
785	789
786	790		glEnter2D;
787	791
788	792		glColor3f(0.2, 0.8 + 0.2 * Sin(GetTotalTime * 5), 0);
789	793		glWrite(20, glGetViewportHeight - 20, GLUT_BITMAP_8_BY_13,
790	794		Format('OpenGL Tutorial :: Bitmap Fonts :: FPS - %.2f FPS', [FPS]));
791	795
792	796		glColor3f(1, 1, 1);
793	797		glWrite(50, glGetViewportHeight - 60, GLUT_BITMAP_9_BY_15, 'GLUT_BITMAP_9_BY_15');
794	798		glWrite(50, glGetViewportHeight - 90, GLUT_BITMAP_8_BY_13, 'GLUT_BITMAP_8_BY_13');
795	799		glWrite(50, glGetViewportHeight - 120, GLUT_BITMAP_TIMES_ROMAN_10, 'GLUT_BITMAP_TIMES_ROMAN_10');
796	800		glWrite(50, glGetViewportHeight - 150, GLUT_BITMAP_TIMES_ROMAN_24, 'GLUT_BITMAP_TIMES_ROMAN_24');
797	801		glWrite(50, glGetViewportHeight - 180, GLUT_BITMAP_HELVETICA_10, 'GLUT_BITMAP_HELVETICA_10');
798	802		glWrite(50, glGetViewportHeight - 210, GLUT_BITMAP_HELVETICA_12, 'GLUT_BITMAP_HELVETICA_12');
799	803		glWrite(50, glGetViewportHeight - 240, GLUT_BITMAP_HELVETICA_18, 'GLUT_BITMAP_HELVETICA_18');
800	804
801	805		glColor3f(0.5, 0.5, 1);
802	806		glWrite(
803	807		glGetViewportWidth - glutBitmapLength(GLUT_BITMAP_9_BY_15, LazText) - 5,
804	808		10, GLUT_BITMAP_9_BY_15, LazText);
805	809
806	810		glLeave2D;
807	811
808	812		glutSwapBuffers;
809	813
810	814		FrameRendered;
811	815		end;
812	816		```
813	817
814	818		![](/wiki-images/b/ba/BitmapFontsPic1.jpg) We draw red cube and rotate it, and some text to show how various bitmap fonts look like. glutBitmapLength function is used to find width of string so it could be aligned to right. Code can easily be altered to center text.
815	819
816	820		Note: See how cube looks without light.
817	821
818	822		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
819	823
820	824		### Textures
821	825
822	826		It's time to use textures :)
823	827
824	828		This tutorial will show how to draw textured polygons and how to blend textures using multipass technic. Since OpenGL has no builtin mechanism for loading textures, we'll use external library: [Vampyre Imaging Library](http://imaginglib.sourceforge.net/). We'll use just OpenGL helper functions, but you may find this lib handy for some other things to.
825	829
826	830		Let's get started... we'll create display list for drawing textured rectangle:
827	831
828	832		``` pascal
829	833		procedure CreateList;
830	834		begin
831	835		glNewList(LIST_OBJECT, GL_COMPILE);
832	836		glBegin(GL_QUADS);
833	837		glTexCoord2f(1, 0);
834	838		glVertex3f( 2, 2, 0);
835	839		glTexCoord2f(0, 0);
836	840		glVertex3f(-2, 2, 0);
837	841		glTexCoord2f(0, 1);
838	842		glVertex3f(-2,-2, 0);
839	843		glTexCoord2f(1, 1);
840	844		glVertex3f( 2,-2, 0);
841	845		glEnd;
842	846		glEndList;
843	847		end;
844	848		```
845	849
846	850		Notice glTexCoord functions. They are used to specify which part of texture is assigned to vertex. Coordinates defined in this functions are from 0 to 1 (values greater than 1 are allowed but can generate different results). 0 is first pixel and 1 is last pixel. So, 0.5 will be right in the middle of texture.
847	851
848	852		Texture loading is extremely easy with Vampyre Imaging Library:
849	853
850	854		``` pascal
851	855		var
852	856		Tex1, Tex2: GLuint;
853	857
854	858		procedure InitializeGL;
855	859		begin
856	860		glClearColor(0, 0, 0, 0);
857	861		Tex1 := LoadGLTextureFromFile('ashwood.bmp');
858	862		Tex2 := LoadGLTextureFromFile('Flare.bmp');
859	863		glEnable(GL_TEXTURE_2D);
860	864		end;
861	865		```
862	866
863	867		LoadGLTextureFromFile loads texture from file and returns it's ID. When texture is loaded it is allready setup for rendering. Last line just enables 2D textures.
864	868
865	869		To draw textured polygon you have to bind texture and setup texture coordinations (texture coordinations are set in display list in this tutorial):
866	870
867	871		``` pascal
868	872		...
869	873		glLoadIdentity;
870	874		glTranslatef(-5, 0, -15);
871	875		glBindTexture(GL_TEXTURE_2D, Tex1);
872	876		glCallList(LIST_OBJECT);
873	877		...
874	878		```
875	879
876	880		glBindTexture function is used to select texture. When you draw polygins they will have selected texture on them. It's that easy :)
877	881
878	882		So, using one texture is easy... but how to blend two textures. Basicly you draw polygon once with one texture, setup blending parameters, and draw polygon once more time with other texture. You can blend houndreds of textures this way. Let's see how code for this looks:
879	883
880	884		``` pascal
881	885		...
882	886		glLoadIdentity;
883	887		glTranslatef(5, 0, -15);
884	888		glBindTexture(GL_TEXTURE_2D, Tex1);
885	889		glCallList(LIST_OBJECT);
886	890
887	891		glEnable(GL_BLEND);
888	892		glBlendFunc(GL_ZERO, GL_SRC_COLOR);
889	893		glLoadIdentity;
890	894		glTranslatef(5, 0, -15);
891	895		glBindTexture(GL_TEXTURE_2D, Tex2);
892	896		glCallList(LIST_OBJECT);
893	897		glDisable(GL_BLEND);
894	898		...
895	899		```
896	900
897	901		As you can see, polygon is drawn first time like we allready know. Before second drawing we enable blending by calling glEnable(GL_BLEND). Blending means that finall pixel color is calculated like this:
898	902
899		-	~~`DrawingColor * SRCBLEND + BackgroundColor * DESTBLEND`~~
	903	+	```text
	904	+	DrawingColor * SRCBLEND + BackgroundColor * DESTBLEND
	905	+	```
900	906
901	907		SRCBLEND and DESTBLEND are defined using glBlendFunc function. In this tutorial we set SRCBLEND to GL_ZERO (zero) and DESTBLENT to GL_SRC_COLOR (DrawingColor) and finall color is then:
902	908
903		-	~~`DrawingColor * 0 + BackgroundColor * DrawingColor`~~
	909	+	```text
	910	+	DrawingColor * 0 + BackgroundColor * DrawingColor
	911	+	```
904	912
905	913		![](/wiki-images/d/d4/TexturesPic1.jpg)
906	914
907	915		This means that background will get darker when you draw with dark colors... when you draw with white color, background color will not be changed. The result will look like this
908	916
909	917		Next time, we'll use extensions to show how to use singlepass multitexturing.
910	918
911	919		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
912	920
913	921		### Multitexturing (extensions)
914	922
915	923		When youknow multipass multi texturing, singlepass is very easy. Texturing is separated in stages. First stage setup and draw first texture, second stage draws another one and so on. All you have to do is to setup texture stages and to render object.
916	924
917	925		Let's see how code looks like:
918	926
919	927		``` pascal
920	928		procedure InitializeGL;
921	929		begin
922	930		Load_GL_ARB_multitexture;
923	931		glClearColor(0, 0, 0, 0);
924	932		Tex1 := LoadGLTextureFromFile('Lazarus.bmp');
925	933		Tex2 := LoadGLTextureFromFile('Mask.bmp');
926	934		glActiveTextureARB(GL_TEXTURE0_ARB);
927	935		glEnable(GL_TEXTURE_2D);
928	936		glBindTexture(GL_TEXTURE_2D, Tex1);
929	937		glActiveTextureARB(GL_TEXTURE1_ARB);
930	938		glEnable(GL_TEXTURE_2D);
931	939		glBindTexture(GL_TEXTURE_2D, Tex2);
932	940		end;
933	941		```
934	942
935	943		First we need load OpenGL extension that will allow us to use multitexture functions. Load_GL_ARB_multitexture will try to load those extensions and will return TRUE if operation was successful.
936	944
937	945		To select texture stage you want to work on, use glActiveTextureARB function. It takes only one parameter that define which stage you want. After that all texture functions (enabling, disabling, binding, creating...) will affect that stage.
938	946
939	947		Since we setup every thing in initialization function, all we have to do is to draw object:
940	948
941	949		``` pascal
942	950		procedure DrawGLScene; cdecl;
943	951		begin
944	952		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
945	953
946	954		glLoadIdentity;
947	955		glTranslatef(0, 0, -5);
948	956
949	957		glBegin(GL_QUADS);
950	958		glMultiTexCoord2fARB(GL_TEXTURE0_ARB, 1, 0);
951	959		glMultiTexCoord2fARB(GL_TEXTURE1_ARB, 1, 0);
952	960		glVertex3f(2.516, 2, 0);
953	961		glMultiTexCoord2fARB(GL_TEXTURE0_ARB, 0, 0);
954	962		glMultiTexCoord2fARB(GL_TEXTURE1_ARB, 0, 0);
955	963		glVertex3f(-2.516, 2, 0);
956	964		glMultiTexCoord2fARB(GL_TEXTURE0_ARB, 0, 1);
957	965		glMultiTexCoord2fARB(GL_TEXTURE1_ARB, 0, 1);
958	966		glVertex3f(-2.516,-2, 0);
959	967		glMultiTexCoord2fARB(GL_TEXTURE0_ARB, 1, 1);
960	968		glMultiTexCoord2fARB(GL_TEXTURE1_ARB, 1, 1);
961	969		glVertex3f(2.516,-2, 0);
962	970		glEnd;
963	971
964	972		glutSwapBuffers;
965	973		end;
966	974		```
967	975
968	976		![](/wiki-images/5/52/MultitexturePic1.jpg) As you can see, difference is only in defining texture coordinations. We now use glMultiTexCoord2fARB function that takes texture stage and texture coordinations. Every thing else is unchanged.
969	977
970	978		Today almost all graphic cards supports at least 2 texture stages. Using singlepass multitexturing is faster than multipass version since you draw objects only once. If hardware supports singlepass multitexturing (Load_GL_ARB_multitexture returns TRUE) use it.
971	979
972	980		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
973	981
974	982		### Render to texture
975	983
976	984		This one will be short. OpenGL can capture current scene to texture so you can use it for texturing other objects (TV screen, mirror or some thing else). Well just render scene to texture and apply it to rotating plane.
977	985
978	986		First, we must create empty texture which we'll use to capture scene:
979	987
980	988		``` pascal
981	989		procedure SetupRenderTexture;
982	990		var
983	991		Data: Pointer;
984	992		begin
985	993		GetMem(Data, 2562563);
986	994		glGenTextures(1, @RenderTexture);
987	995		glBindTexture(GL_TEXTURE_2D, RenderTexture);
988	996		glTexImage2D(GL_TEXTURE_2D, 0, 3, 256, 256, 0, GL_RGB, GL_UNSIGNED_BYTE, Data);
989	997		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
990	998		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
991	999		FreeMem(Data);
992	1000		end;
993	1001		```
994	1002
995	1003		Buffer for 256*256 RGB image is created and it is used to setup 2D texture.
996	1004
997	1005		Main part is in drawing function:
998	1006
999	1007		``` pascal
1000	1008		procedure DrawGLScene; cdecl;
1001	1009		var
1002	1010		TotalTime: Single;
1003	1011		begin
1004	1012		glClearColor(0, 0, 0, 0);
1005	1013		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
1006	1014		glEnable(GL_LIGHTING);
1007	1015		glDisable(GL_TEXTURE_2D);
1008	1016		glViewport(0, 0, 256, 256);
1009	1017
1010	1018		TotalTime := GetTotalTime;
1011	1019
1012	1020		glLoadIdentity;
1013	1021		glTranslatef(0, 0, -5);
1014	1022		glRotatef(50 * TotalTime, 1, 0, 0);
1015	1023		glRotatef(100 * TotalTime, 0, 1, 0);
1016	1024		glRotatef(50 * TotalTime, 0, 0, 1);
1017	1025
1018	1026		glColor3f(1, 1, 1);
1019	1027		glutSolidCube(2);
1020	1028
1021	1029		glCopyTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, 0, 0, 256, 256, 0);
1022	1030
1023	1031		glClearColor(0.18, 0.20, 0.66, 0);
1024	1032		glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT);
1025	1033		glDisable(GL_LIGHTING);
1026	1034		glEnable(GL_TEXTURE_2D);
1027	1035		glViewport(0, 0, AppWidth, AppHeight);
1028	1036
1029	1037		glLoadIdentity;
1030	1038		glTranslatef(0, 0, -7);
1031	1039		glRotatef(20 * TotalTime, 1, 0, 0);
1032	1040		glRotatef(50 * TotalTime, 0, 1, 0);
1033	1041
1034	1042		glBegin(GL_QUADS);
1035	1043		glTexCoord2f(1, 0);
1036	1044		glVertex3f(2, 2, 0);
1037	1045		glTexCoord2f(0, 0);
1038	1046		glVertex3f(-2, 2, 0);
1039	1047		glTexCoord2f(0, 1);
1040	1048		glVertex3f(-2,-2, 0);
1041	1049		glTexCoord2f(1, 1);
1042	1050		glVertex3f(2,-2, 0);
1043	1051		glEnd;
1044	1052
1045	1053		glutSwapBuffers;
1046	1054		end;
1047	1055		```
1048	1056
1049	1057		![](/wiki-images/6/6e/RenderToTexturePic1.jpg) First, everything is setup for scene that will be captured. Viewport is reduced to 256*256 so it will fit into texture and scene is drawn. glCopyTexImage2D is used to capture scene to currently selected texture.
1050	1058
1051	1059		When we have scene captured to texture, everything can be cleared again, viewport can be returned to original size and final scene is drawn using previous scene as texture.
1052	1060
1053	1061		P.S. Captured texture can be saved using SaveGLTextureToFile function from [Vampyre Imaging Library](http://imaginglib.sourceforge.net/).
1054	1062
1055	1063		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
1056	1064
1057	1065		### Vertex array
1058	1066
1059	1067		OpenGL is capable of rendering primitives using data that is stored in buffers insted of calling glVertex. Buffers can be used to define vertex and texture coordinates, and colors (index and RGBA), normals and edge flags.
1060	1068
1061	1069		In this tutorial well use only vertex and color buffers, and we'll show non-indexed and indexed drawing. Non-indexed mode draws buffers as streams. Indexed mode will draw buffer elements in order that is defined in index buffer. But enough talking... let's start coding.
1062	1070
1063	1071		First, let's define some types and constants:
1064	1072
1065	1073		``` pascal
1066	1074		type
1067	1075		TVertex3f = record
1068	1076		X, Y, Z: Single;
1069	1077		end;
1070	1078
1071	1079		TColor3f = record
1072	1080		R, G, B: Single;
1073	1081		end;
1074	1082
1075	1083		VertexBuffer: array [0..5] of TVertex3f = (
1076	1084		(X : 1; Y : 1; Z : 0),
1077	1085		(X : -1; Y : 1; Z : 0),
1078	1086		(X : -1; Y : -1; Z : 0),
1079	1087		(X : 1; Y : 1; Z : 0),
1080	1088		(X : -1; Y : -1; Z : 0),
1081	1089		(X : 1; Y : -1; Z : 0)
1082	1090		);
1083	1091		ColorBuffer: array [0..5] of TColor3f = (
1084	1092		(R : 1; G : 0; B : 1),
1085	1093		(R : 0; G : 0; B : 1),
1086	1094		(R : 0; G : 1; B : 0),
1087	1095		(R : 1; G : 0; B : 1),
1088	1096		(R : 0; G : 1; B : 0),
1089	1097		(R : 1; G : 1; B : 0)
1090	1098		);
1091	1099		```
1092	1100
1093	1101		We have two buffers. One for vertex coordinates and one for vertex colors. This 6 vertices defines 2 triangles that forms rectangle.
1094	1102
1095	1103		Drawing primitives using buffers is easy:
1096	1104
1097	1105		``` pascal
1098	1106		glEnableClientState(GL_VERTEX_ARRAY);
1099	1107		glEnableClientState(GL_COLOR_ARRAY);
1100	1108		glVertexPointer(3, GL_FLOAT, 0, @VertexBuffer[0]);
1101	1109		glColorPointer(3, GL_FLOAT, 0, @ColorBuffer[0]);
1102	1110
1103	1111		glDrawArrays(GL_TRIANGLES, 0, Length(VertexBuffer));
1104	1112
1105	1113		glDisableClientState(GL_VERTEX_ARRAY);
1106	1114		glDisableClientState(GL_COLOR_ARRAY);
1107	1115		```
1108	1116
1109	1117		First we enable buffers we want to use using glEnableClientState function. Than we can select buffers we want to use. Every buffer type has own function for selecting (glColorPointer, glEdgeFlagPointer, glIndexPointer, glNormalPointer, glTexCoordPointer, glVertexPointer). First parameter in those functions defines how many numbers every element contains. For example, let's take vertex buffer. If this parameter is 2 than OpenGL expects that every element in buffer contains x and y coordinate. If this parameter is, for example, 4, than every element should contains x, y, z and w coordinate. Next parameter defines what type of data element contains (GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT or GL_DOUBLE). Next one defines how many bytes are between each element. This way you can have buffer that contains vertex coordinates and some custom data. For arbitrary data type, this parameter can be calculated like this:
1110	1118
1111	1119		``` pascal
1112	1120		type
1113	1121		TBufferData = record
1114	1122		DataBefore: TDataBefore;
1115	1123		Vertex: TVertex;
1116	1124		DataAfter: TDataAfter;
1117	1125		end;
1118	1126		```
1119	1127
1120		-	~~`Bytes between elements = SizeOf(TDataBefore) + SizeOf(TDataAfter)`~~
	1128	+	```text
	1129	+	Bytes between elements = SizeOf(TDataBefore) + SizeOf(TDataAfter)
	1130	+	```
1121	1131
1122	1132		Last parameter if pointer to the begginig of buffer.
1123	1133
1124	1134		When buffers are selected we can draw them using glDrawArrays functions. All enabled buffers are used to draw primitives. What kind of polygons are being generated is defined in first parameter (same as in glBegin function). Next two defines subset of buffer which is used for drawing (start and count).
1125	1135
1126	1136		When buffers are not needed you can disable them.
1127	1137
1128	1138		To demonstrate indexed mode, I made some simple mesh class that can load vertex, color and index data from external files:
1129	1139
1130	1140		``` pascal
1131	1141		type
1132	1142		TMesh = class
1133	1143		private
1134	1144		FVertices: array of TVertex3f;
1135	1145		FColors: array of TColor3f;
1136	1146		FIndices: array of Integer;
1137	1147		procedure FreeBuffers;
1138	1148		public
1139	1149		constructor Create;
1140	1150		destructor Destroy; override;
1141	1151		procedure LoadMesh(FileName: String);
1142	1152		procedure DrawMesh;
1143	1153		end;
1144	1154		```
1145	1155
1146	1156		FVertices will contain data about vertices, FColors data about color and FIndices data about indices when external file is loaded.
1147	1157
1148	1158		First we'll write some code that deals with creation and destruction of class:
1149	1159
1150	1160		``` pascal
1151	1161		procedure TMesh.FreeBuffers;
1152	1162		begin
1153	1163		FVertices := nil;
1154	1164		FColors := nil;
1155	1165		FIndices := nil;
1156	1166		end;
1157	1167
1158	1168		constructor TMesh.Create;
1159	1169		begin
1160	1170		FreeBuffers;
1161	1171		end;
1162	1172
1163	1173		destructor TMesh.Destroy;
1164	1174		begin
1165	1175		FreeBuffers;
1166	1176		inherited Destroy;
1167	1177		end;
1168	1178		```
1169	1179
1170	1180		File that will contain mesh data is simple text file. First row will contain number of vertices and indices separated by space character. After that row will come rows for every vertex and color. X, Y, Z, R, G and B all separated by space character. In the end, there will be rows for indices... every index number is written in its own row... so, for one triangle, data file will look like this:
1171	1181
1172		-	~~`3 3`\~~
1173		-	~~`-1 -1 0 1 1 1`\~~
1174		-	~~`1 -1 0 1 1 1`\~~
1175		-	~~`0 1 0 1 1 1`\~~
1176		-	~~`0`\~~
1177		-	~~`1`\~~
1178		-	~~`2`~~
	1182	+	```text
	1183	+	3 3
	1184	+	-1 -1 0 1 1 1
	1185	+	1 -1 0 1 1 1
	1186	+	0 1 0 1 1 1
	1187	+	0
	1188	+	1
	1189	+	2
	1190	+	```
1179	1191
1180	1192		This means that there is 3 vertices and 3 indices defined in file. First vrtex is at -1, -1, 0 and has color 1, 1, 1 and so on. Indices defines that order in which vertices are drawn (in this case vertices are drawn in the same order as they are defined).
1181	1193
1182	1194		Code for loading this data will loke like this:
1183	1195
1184	1196		``` pascal
1185	1197		procedure TMesh.LoadMesh(FileName: String);
1186	1198		var
1187	1199		MeshFile: TextFile;
1188	1200		VertexCount, IndexCount: Integer;
1189	1201		iV, iI: Integer;
1190	1202		begin
1191	1203		FreeBuffers;
1192	1204
1193	1205		AssignFile(MeshFile, FileName);
1194	1206		Reset(MeshFile);
1195	1207
1196	1208		ReadLn(MeshFile, VertexCount, IndexCount);
1197	1209
1198	1210		SetLength(FVertices, VertexCount);
1199	1211		SetLength(FColors, VertexCount);
1200	1212		SetLength(FIndices, IndexCount);
1201	1213
1202	1214		for iV := 0 to VertexCount - 1 do
1203	1215		ReadLn(MeshFile,
1204	1216		FVertices[iV].X, FVertices[iV].Y, FVertices[iV].Z,
1205	1217		FColors[iV].R, FColors[iV].G, FColors[iV].B);
1206	1218
1207	1219		for iI := 0 to IndexCount - 1 do
1208	1220		ReadLn(MeshFile, FIndices[iI]);
1209	1221
1210	1222		CloseFile(MeshFile);
1211	1223		end;
1212	1224		```
1213	1225
1214	1226		After loading data, we have everything for drawing:
1215	1227
1216	1228		``` pascal
1217	1229		procedure TMesh.DrawMesh;
1218	1230		begin
1219	1231		glEnableClientState(GL_VERTEX_ARRAY);
1220	1232		glEnableClientState(GL_COLOR_ARRAY);
1221	1233		glVertexPointer(3, GL_FLOAT, 0, @FVertices[0]);
1222	1234		glColorPointer(3, GL_FLOAT, 0, @FColors[0]);
1223	1235
1224	1236		glDrawElements(GL_TRIANGLES, Length(FIndices), GL_UNSIGNED_INT, @FIndices[0]);
1225	1237
1226	1238		glDisableClientState(GL_VERTEX_ARRAY);
1227	1239		glDisableClientState(GL_COLOR_ARRAY);
1228	1240		end;
1229	1241		```
1230	1242
1231	1243		As you can see, allmost everything is the same as for non-indexed drawing, except function that actually draw polygons. In this case we use glDrawElements function. For this one we specify what kind of polygons we want, how many indices are in index buffer, type of data in index buffer and pointer to the beginning of index buffer.
1232	1244
1233	1245		![](/wiki-images/7/77/VertexArrayPic1.jpg)Full source code comes with mesh data file that this class can use to generates rectangle that is identical with one that is drawn using non-indexed mode. Mesh data file looks like this:
1234	1246
1235		-	~~`4 6`\~~
1236		-	~~`1 1 0 1 0 1`\~~
1237		-	~~`-1 1 0 0 0 1`\~~
1238		-	~~`-1 -1 0 0 1 0`\~~
1239		-	~~`1 -1 0 1 1 0`\~~
1240		-	~~`0`\~~
1241		-	~~`1`\~~
1242		-	~~`2`\~~
1243		-	~~`0`\~~
1244		-	~~`2`\~~
1245		-	~~`3`~~
	1247	+	```text
	1248	+	4 6
	1249	+	1 1 0 1 0 1
	1250	+	-1 1 0 0 0 1
	1251	+	-1 -1 0 0 1 0
	1252	+	1 -1 0 1 1 0
	1253	+	0
	1254	+	1
	1255	+	2
	1256	+	0
	1257	+	2
	1258	+	3
	1259	+	```
1246	1260
1247	1261		As you can see, there is data for only 4 vertices and 6 indices. So, first triangle is defined by vertices 0, 1 and 2, and the seccond one by vertices 0, 2 and 3. By using indexed mode we don't have to duplicate vertices.
1248	1262
1249	1263		Download source code, linux executable or windows executable from [Lazarus CCR SourceForge](http://sourceforge.net/projects/lazarus-ccr/files/OpenGL%20Tutorial/).
1250	1264
1251	1265		## Modern OpenGL using macOS
1252	1266
1253	1267		> Note: the macOS OpenGL implementation is stuck at version 4.1 from 2010 and was deprecated by Apple on the release of macOS 10.14 (Mojave) in September 2018.
1254	1268
1255	1269		A great feature of Lazarus is "write once, compile anywhere", where code should just work on macOS, Linux or Windows. However, to support all three of these systems you need to decide whether to only support legacy OpenGL or to use the leander "OpenGL Core" profile. For Linux and Windows users, recent versions of OpenGL are a superset of older versions. Therefore, a Linux user can mix and match old OpenGL code with modern shaders. This is not the case for Macintosh macOS (nee OS X) users.
1256	1270
1257	1271		macOS provides two forms of support: the legacy mode supports all OpenGL features up to 2.1 (and GLSL 1.2). Alternatively, the user can select a modern core version of OpenGL (whereas most Linux and Windows users have access to the compatibility versions of OpenGL). The core versions of OpenGL [remove many deprecated legacy functions](http://github.prideout.net/modern-opengl-prezo/). This means that all the tutorials above will only compile in macOS's legacy mode. The core mode has no fixed function pipeline and therefore the developer must write their own shaders. In addition, the Core mode removes some [basic primitives like GL_QUADS](https://www.opengl.org/wiki/Legacy_OpenGL), so a quad needs to be replaced by two triangles (this actually makes sense: all vertices of a triangle are coplanar, but this is not necessarily the case for a quad, just like each leg of a 3-legged stool will always touch the ground, while a 4-legged stool might wobble if one leg is shorter than the others).
1258	1272
1259	1273		The benefit of the core model is that it is lean, and generally easy to adapt to mobile devices (which use a similar, embedded form of OpenGL). See [Apple's website](https://developer.apple.com/opengl/capabilities/) to see the OpenGL supported by your operating system. A further wrinkle is that the Core modes of OpenGL are only supported on the Cocoa widgetset, so you can not use the Carbon widgetset. Three demo projects are available on [Github](https://github.com/neurolabusc/OpenGLCoreTutorials), and will compile using Lazarus 1.6.2 or later on Linux, Windows or macOS.
1260	1274
1261	1275		## See also
1262	1276
1263	1277		- [[Creating bindings for C libraries]]
1264	1278		- [[OpenGL]]
1265	1279
1266	1280		## External links
1267	1281
1268	1282		- [OpenGL Light Tutorial](http://www.falloutsoftware.com/tutorials/gl/gl8.htm) - An OpenGL tutorial outlining how to create and manipulate lights, as well as deal with polygon surface reflections using normals.
1269	1283		- [Apple OpenGL Documentation](https://developer.apple.com/library/archive/documentation/GraphicsImaging/Conceptual/OpenGL-MacProgGuide/opengl_pg_concepts/opengl_pg_concepts.html).
1270	1284
1271	1285		---
1272	1286		From the Free Pascal wiki, page "OpenGL Tutorial", as it stood on 2021-04-16 after a change by Trev, 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).

Back to history