ZenGL Tutorial: what changed

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

Title: ZenGL Tutorial

New		Line
1	+	## Download
2	+
3	+	You can get [[ZenGL]] for Linux, Windows & Mac [at the ZenGL homepage](http://zengl.org/download.html).
4	+
5	+	## Installation
6	+
7	+	You can extract the downloaded compressed archive with an utility like 7-Zip to a folder of your choice.
8	+
9	+	### Source Path
10	+
11	+	Before using any of the modules, make sure you set the correct path to the source code of ZenGL.
12	+
13	+	Go to "Project \> Project Options". In "Compiler Options \> Paths" and you can add these in "Other Unit Files":
14	+
15	+	```text
16	+	headers
17	+	extra
18	+	src
19	+	src\Direct3D
20	+	lib\jpeg\$(TargetCPU)-$(TargetOS)
21	+	lib\msvcrt\$(TargetCPU)
22	+	lib\ogg\$(TargetCPU)-$(TargetOS)
23	+	lib\zlib\$(TargetCPU)-$(TargetOS)
24	+	```
25	+
26	+	## Compilation
27	+
28	+	Application can be compiled with ZenGL statically or with a .so/.dll/.dylib.
29	+
30	+	Read more about [compiling](http://zengl.org/wiki/doku.php?id=compilation:basics) ZenGL in the [ZenGL Wiki](http://zengl.org/wiki/).
31	+
32	+	### Compiling ZenGL statically
33	+
34	+	The advantage of static compilation is a smaller size of your application, but it requires including all units.
35	+
36	+	``` pascal
37	+	{$DEFINE STATIC}
38	+	```
39	+
40	+	### ZenGL using a .so/.dll/.dylib
41	+
42	+	Using a .so/.dll/.dylib doesn't require you to open source the code of your application. To do this comment out or delete the \$DEFINE STATIC compiler directive. You also need to compile the ZenGL library.
43	+
44	+	``` pascal
45	+	//{$DEFINE STATIC}
46	+	```
47	+
48	+	#### Windows dll
49	+
50	+	Open "src\Lazarus\ZenGL.lpi" then go to "Run \> Compile (Ctrl + F9)".
51	+
52	+	Then in the directory "src\" you should see the file "ZenGL.dll", copy and paste it in the folder "bin\i386" where all the demo binaries are compiled. You always must copy the libraries in your program output directory if you are using the .dll.
53	+
54	+	Now you can compile the demos, commenting out the \$DEFINE STATIC.
55	+
56	+	Other .dll files in the "bin\" folder you can use are: `chipmunk.dll ; libogg-0.dll ; libvorbis-0.dll ; libvorbis-3.dll`
57	+
58	+	## First Program
59	+
60	+	This is the first demo program included with ZenGL. First create a new "Free Pascal Program". Add the Source Path as described before.
61	+
62	+	You must also change the Syntax Mode inProject \> Project Options \> Compiler Options \> Parsing to Delphi (-Mdelphi).
63	+
64	+	Remember, if you are using a .so/.dll/.dylib copy the library binaries to the output folder of your program.
65	+
66	+	Program title, add resources:
67	+
68	+	``` pascal
69	+	program demo01;
70	+
71	+	{$R *.res}
72	+	```
73	+
74	+	Define compilation mode (comment out to use .so/.dll/.dylib):
75	+
76	+	``` pascal
77	+	{$DEFINE STATIC}
78	+	```
79	+
80	+	This adds the ZenGL units:
81	+
82	+	``` pascal
83	+	uses
84	+	{$IFNDEF STATIC}
85	+	zglHeader
86	+	{$ELSE}
87	+	zgl_main,
88	+	zgl_screen,
89	+	zgl_window,
90	+	zgl_timers,
91	+	zgl_utils
92	+	{$ENDIF}
93	+	;
94	+	```
95	+
96	+	Variables like in a standard pascal program:
97	+
98	+	``` pascal
99	+	var
100	+	DirApp : String;
101	+	DirHome : String;
102	+	```
103	+
104	+	Procedures, add your code here:
105	+
106	+	``` pascal
107	+	procedure Init;
108	+	begin
109	+	// Here you can load the main resources.
110	+	end;
111	+
112	+	procedure Draw;
113	+	begin
114	+	// Here you can "draw" anything.
115	+	end;
116	+
117	+	procedure Update( dt : Double );
118	+	begin
119	+	// This function is the best way to implement smooth moving of something, because timers are restricted by FPS.
120	+	end;
121	+
122	+	procedure Timer;
123	+	begin
124	+	// This caption will show the frames per second.
125	+	wnd_SetCaption( '01 - Initialization[ FPS: ' + u_IntToStr( zgl_Get( RENDER_FPS ) ) + ' ]' );
126	+	end;
127	+
128	+	procedure Quit;
129	+	begin
130	+	//
131	+	end;
132	+	```
133	+
134	+	The program starts here:
135	+
136	+	``` pascal
137	+	Begin
138	+	{$IFNDEF STATIC}
139	+	zglLoad( libZenGL );
140	+	{$ENDIF}
141	+	// For loading/creating your own options/profiles/etc. you can get the path to the user home
142	+	// directory, or to the executable file (does not work on GNU/Linux).
143	+	DirApp := u_CopyStr( PChar( zgl_Get( DIRECTORY_APPLICATION ) ) );
144	+	DirHome := u_CopyStr( PChar( zgl_Get( DIRECTORY_HOME ) ) );
145	+
146	+	// Create a timer with an interval of 1000ms.
147	+	timer_Add( @Timer, 1000 );
148	+
149	+	// Register the procedure that will be executed after ZenGL initialization.
150	+	zgl_Reg( SYS_LOAD, @Init );
151	+	// Register the render procedure.
152	+	zgl_Reg( SYS_DRAW, @Draw );
153	+	// Register the procedure that will get the delta time between the frames.
154	+	zgl_Reg( SYS_UPDATE, @Update );
155	+	// Register the procedure that will be called after ZenGL shuts down.
156	+	zgl_Reg( SYS_EXIT, @Quit );
157	+
158	+	// Enable usage of UTF-8, because this unit saved in UTF-8 encoding and here used
159	+	// string variables.
160	+	zgl_Enable( APP_USE_UTF8 );
161	+
162	+	// Set the caption of the window.
163	+	wnd_SetCaption( '01 - Initialization' );
164	+
165	+	// Show the mouse cursor.
166	+	wnd_ShowCursor( TRUE );
167	+
168	+	// Set screen options.
169	+	scr_SetOptions( 800, 600, REFRESH_MAXIMUM, FALSE, FALSE );
170	+
171	+	// Initialize ZenGL.
172	+	zgl_Init();
173	+	End.
174	+	```
175	+
176	+	### Resulting Code
177	+
178	+	The result is a template for ZenGL projects:
179	+
180	+	``` pascal
181	+	program template;
182	+
183	+	{$DEFINE STATIC}
184	+
185	+	{$R *.res}
186	+
187	+	uses
188	+	{$IFNDEF STATIC}
189	+	zglHeader
190	+	{$ELSE}
191	+	zgl_main,
192	+	zgl_screen,
193	+	zgl_window,
194	+	zgl_timers,
195	+	zgl_utils
196	+	{$ENDIF}
197	+	;
198	+
199	+	var
200	+	DirApp : String; DirHome : String;
201	+
202	+	procedure Init;
203	+	begin
204	+	end;
205	+
206	+	procedure Draw;
207	+	begin
208	+	end;
209	+
210	+	procedure Update( dt : Double );
211	+	begin
212	+	end;
213	+
214	+	procedure Timer;
215	+	begin
216	+	wnd_SetCaption( '01 - Initialization[ FPS: ' + u_IntToStr( zgl_Get( RENDER_FPS ) ) + ' ]' );
217	+	end;
218	+
219	+	procedure Quit;
220	+	begin
221	+	end;
222	+
223	+	Begin
224	+	{$IFNDEF STATIC}
225	+	zglLoad( libZenGL );
226	+	{$ENDIF}
227	+	DirApp := u_CopyStr( PChar( zgl_Get( DIRECTORY_APPLICATION ) ) );
228	+	DirHome := u_CopyStr( PChar( zgl_Get( DIRECTORY_HOME ) ) );
229	+	timer_Add( @Timer, 1000 );
230	+	zgl_Reg( SYS_LOAD, @Init );
231	+	zgl_Reg( SYS_DRAW, @Draw );
232	+	zgl_Reg( SYS_UPDATE, @Update );
233	+	zgl_Reg( SYS_EXIT, @Quit );
234	+	zgl_Enable( APP_USE_UTF8 );
235	+	wnd_SetCaption( '01 - Initialization' );
236	+	wnd_ShowCursor( TRUE );
237	+	scr_SetOptions( 800, 600, REFRESH_MAXIMUM, FALSE, FALSE );
238	+	zgl_Init();
239	+	End.
240	+	```
241	+
242	+	---
243	+	From the Free Pascal wiki, page "ZenGL Tutorial", as it stood on 2020-03-03 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