Difference between revisions of "ZenGL Tutorial"

From Lazarus wiki
Jump to navigationJump to search
m (removed note about LGPL, as ZenGL has switched to the zlib license.)
m (Cleaning up a bit)
Line 5: Line 5:
 
== Download ==
 
== Download ==
  
You can get [[ZenGL]] for Linux, Windows & Mac. [http://zengl.org/download.html Download ZenGL].
+
You can get [[ZenGL]] for Linux, Windows & Mac [http://zengl.org/download.html at the ZenGL homepage].
  
 
== Installation ==
 
== Installation ==
  
Just extract the downloaded file with a compressed files manager, like 7-Zip in the folder you want.
+
You can extract the downloaded compressed archive with an utility like 7-Zip to a folder of your choice.
  
 
=== Source Path ===
 
=== Source Path ===
  
Before using the modules don't forget to set path to source code of ZenGL.
+
Before using any of the modules, make sure you set the correct path to the source code of ZenGL.
  
Go to "''Project > Project Options''". In "''Compiler Options > Paths''" you must add those in "''Other Unit Files''":
+
Go to "''Project > Project Options''". In "''Compiler Options > Paths''" and you can add these in "''Other Unit Files''":
  
 
<syntaxhighlight>headers
 
<syntaxhighlight>headers
Line 28: Line 28:
 
== Compilation ==
 
== Compilation ==
  
Application can be compiled with ZenGL statically or with using so/dll/dylib.
+
Application can be compiled with ZenGL statically or with a .so/.dll/.dylib.
  
Read more about [http://zengl.org/wiki/doku.php?id=compilation compilation] in the [http://zengl.org/wiki/ ZenGL Wiki].
+
Read more about [http://zengl.org/wiki/doku.php?id=compilation:basics compiling] ZenGL in the [http://zengl.org/wiki/ ZenGL Wiki].
  
=== ZenGL statically ===
+
=== Compiling ZenGL statically ===
  
Advantage of static compilation is smaller size of application, but it requires including all units.
+
The advantage of static compilation is a smaller size of your application, but it requires including all units.
  
 
<syntaxhighlight>{$DEFINE STATIC}</syntaxhighlight>
 
<syntaxhighlight>{$DEFINE STATIC}</syntaxhighlight>
  
=== ZenGL using so/dll/dylib ===
+
=== ZenGL using a .so/.dll/.dylib ===
  
Using so/dll/dylib doesn't require to open source code of your application. For this comment the ''$DEFINE STATIC''. Also you need to compile ZenGL library.
+
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.
  
 
<syntaxhighlight>//{$DEFINE STATIC}</syntaxhighlight>
 
<syntaxhighlight>//{$DEFINE STATIC}</syntaxhighlight>
Line 48: Line 48:
 
Open "''src\Lazarus\ZenGL.lpi''" then go to "''Run > Compile (Ctrl + F9)''".
 
Open "''src\Lazarus\ZenGL.lpi''" then go to "''Run > Compile (Ctrl + F9)''".
  
Then in the directory "''src\''" you can see the file "''ZenGL.dll''", copy and paste in the folder "''bin\i386''" where all demo binaries are compiled. You always must copy libraries in your program output directory if you are using dll.
+
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.
  
Now you can compile demos commenting the ''$DEFINE STATIC''.
+
Now you can compile the demos, commenting out the ''$DEFINE STATIC''.
  
Other dll files in "''bin\''" folder you can use are: <code>chipmunk.dll ; libogg-0.dll ; libvorbis-0.dll ; libvorbis-3.dll</code>
+
Other .dll files in the "''bin\''" folder you can use are: <code>chipmunk.dll ; libogg-0.dll ; libvorbis-0.dll ; libvorbis-3.dll</code>
  
 
== First Program ==
 
== First Program ==
  
This is the first demo program included with ZenGL, first create a new "Free Pascal Program". Add the Source Path as described before.
+
This is the first demo program included with ZenGL. First create a new "Free Pascal Program". Add the Source Path as described before.
  
Also you must change the ''Syntax Mode'' in'' Project > Project Options > Compiler Options > Parsing'' to ''Delphi (-Mdelphi)''.
+
You must also change the ''Syntax Mode'' in'' Project > Project Options > Compiler Options > Parsing'' to ''Delphi (-Mdelphi)''.
  
Remember, if you are using so/dll/dylib copy the library binaries to the output folder of your program.
+
Remember, if you are using a .so/.dll/.dylib copy the library binaries to the output folder of your program.
  
 
Program title, add resources:
 
Program title, add resources:
Line 67: Line 67:
 
{$R *.res}</syntaxhighlight>
 
{$R *.res}</syntaxhighlight>
  
Define compilation mode (comment to use so/dll/dylib):
+
Define compilation mode (comment out to use .so/.dll/.dylib):
 
<syntaxhighlight>{$DEFINE STATIC}</syntaxhighlight>
 
<syntaxhighlight>{$DEFINE STATIC}</syntaxhighlight>
  
This add the ZenGL units.
+
This adds the ZenGL units:
 
<syntaxhighlight>uses
 
<syntaxhighlight>uses
 
   {$IFNDEF STATIC}
 
   {$IFNDEF STATIC}
Line 89: Line 89:
 
   DirHome : String;</syntaxhighlight>
 
   DirHome : String;</syntaxhighlight>
  
Procedures to add code:
+
Procedures, add your code here:
 
<syntaxhighlight>procedure Init;
 
<syntaxhighlight>procedure Init;
 
begin
 
begin
   // Here can be loading of main resources.
+
   // Here you can load the main resources.
 
end;
 
end;
  
 
procedure Draw;
 
procedure Draw;
 
begin
 
begin
   // Here "draw" anything.
+
   // Here you can "draw" anything.
 
end;
 
end;
  
Line 107: Line 107:
 
procedure Timer;
 
procedure Timer;
 
begin
 
begin
   // Caption will show the frames per second.
+
   // This caption will show the frames per second.
 
   wnd_SetCaption( '01 - Initialization[ FPS: ' + u_IntToStr( zgl_Get( RENDER_FPS ) ) + ' ]' );
 
   wnd_SetCaption( '01 - Initialization[ FPS: ' + u_IntToStr( zgl_Get( RENDER_FPS ) ) + ' ]' );
 
end;
 
end;
Line 116: Line 116:
 
end;</syntaxhighlight>
 
end;</syntaxhighlight>
  
Here start the program:
+
The program starts here:
 
<syntaxhighlight>Begin
 
<syntaxhighlight>Begin
 
   {$IFNDEF STATIC}
 
   {$IFNDEF STATIC}
 
   zglLoad( libZenGL );
 
   zglLoad( libZenGL );
 
   {$ENDIF}
 
   {$ENDIF}
   // For loading/creating your own options/profiles/etc. you can get path to user home
+
   // For loading/creating your own options/profiles/etc. you can get the path to the user home
   // directory, or to executable file(not works for GNU/Linux).
+
   // directory, or to the executable file (does not work on GNU/Linux).
 
   DirApp  := u_CopyStr( PChar( zgl_Get( DIRECTORY_APPLICATION ) ) );
 
   DirApp  := u_CopyStr( PChar( zgl_Get( DIRECTORY_APPLICATION ) ) );
 
   DirHome := u_CopyStr( PChar( zgl_Get( DIRECTORY_HOME ) ) );
 
   DirHome := u_CopyStr( PChar( zgl_Get( DIRECTORY_HOME ) ) );
  
   // Create a timer with interval 1000ms.
+
   // Create a timer with an interval of 1000ms.
 
   timer_Add( @Timer, 1000 );
 
   timer_Add( @Timer, 1000 );
  
   // Register the procedure, that will be executed after ZenGL initialization.
+
   // Register the procedure that will be executed after ZenGL initialization.
 
   zgl_Reg( SYS_LOAD, @Init );
 
   zgl_Reg( SYS_LOAD, @Init );
 
   // Register the render procedure.
 
   // Register the render procedure.
 
   zgl_Reg( SYS_DRAW, @Draw );
 
   zgl_Reg( SYS_DRAW, @Draw );
   // Register the procedure, that will get delta time between the frames.
+
   // Register the procedure that will get the delta time between the frames.
 
   zgl_Reg( SYS_UPDATE, @Update );
 
   zgl_Reg( SYS_UPDATE, @Update );
   // Register the procedure, that will be executed after ZenGL shutdown.
+
   // Register the procedure that will be called after ZenGL shuts down.
 
   zgl_Reg( SYS_EXIT, @Quit );
 
   zgl_Reg( SYS_EXIT, @Quit );
 
    
 
    
   // Enable using of UTF-8, because this unit saved in UTF-8 encoding and here used
+
   // Enable usage of UTF-8, because this unit saved in UTF-8 encoding and here used
 
   // string variables.
 
   // string variables.
 
   zgl_Enable( APP_USE_UTF8 );
 
   zgl_Enable( APP_USE_UTF8 );
Line 145: Line 145:
 
   wnd_SetCaption( '01 - Initialization' );
 
   wnd_SetCaption( '01 - Initialization' );
  
   // Allow to show the mouse cursor.
+
   // Show the mouse cursor.
 
   wnd_ShowCursor( TRUE );
 
   wnd_ShowCursor( TRUE );
  

Revision as of 23:03, 1 February 2013

Deutsch (de) English (en) español (es) français (fr) русский (ru)


ZenGL | Tutorial 1 | Tutorial 2 | Tutorial 3 | Edit

Download

You can get ZenGL for Linux, Windows & Mac at the ZenGL homepage.

Installation

You can extract the downloaded compressed archive with an utility like 7-Zip to a folder of your choice.

Source Path

Before using any of the modules, make sure you set the correct path to the source code of ZenGL.

Go to "Project > Project Options". In "Compiler Options > Paths" and you can add these in "Other Unit Files":

headers
extra
src
src\Direct3D
lib\jpeg\$(TargetCPU)-$(TargetOS)
lib\msvcrt\$(TargetCPU)
lib\ogg\$(TargetCPU)-$(TargetOS)
lib\zlib\$(TargetCPU)-$(TargetOS)

Compilation

Application can be compiled with ZenGL statically or with a .so/.dll/.dylib.

Read more about compiling ZenGL in the ZenGL Wiki.

Compiling ZenGL statically

The advantage of static compilation is a smaller size of your application, but it requires including all units.

{$DEFINE STATIC}

ZenGL using a .so/.dll/.dylib

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.

//{$DEFINE STATIC}

Windows dll

Open "src\Lazarus\ZenGL.lpi" then go to "Run > Compile (Ctrl + F9)".

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.

Now you can compile the demos, commenting out the $DEFINE STATIC.

Other .dll files in the "bin\" folder you can use are: chipmunk.dll ; libogg-0.dll ; libvorbis-0.dll ; libvorbis-3.dll

First Program

This is the first demo program included with ZenGL. First create a new "Free Pascal Program". Add the Source Path as described before.

You must also change the Syntax Mode in Project > Project Options > Compiler Options > Parsing to Delphi (-Mdelphi).

Remember, if you are using a .so/.dll/.dylib copy the library binaries to the output folder of your program.

Program title, add resources:

program demo01;

{$R *.res}

Define compilation mode (comment out to use .so/.dll/.dylib):

{$DEFINE STATIC}

This adds the ZenGL units:

uses
  {$IFNDEF STATIC}
  zglHeader
  {$ELSE}
  zgl_main,
  zgl_screen,
  zgl_window,
  zgl_timers,
  zgl_utils
  {$ENDIF}
  ;

Variables like in a standard pascal program:

var
  DirApp  : String;
  DirHome : String;

Procedures, add your code here:

procedure Init;
begin
  // Here you can load the main resources.
end;

procedure Draw;
begin
  // Here you can "draw" anything.
end;

procedure Update( dt : Double );
begin
  // This function is the best way to implement smooth moving of something, because timers are restricted by FPS.
end;

procedure Timer;
begin
  // This caption will show the frames per second.
  wnd_SetCaption( '01 - Initialization[ FPS: ' + u_IntToStr( zgl_Get( RENDER_FPS ) ) + ' ]' );
end;

procedure Quit;
begin
 //
end;

The program starts here:

Begin
  {$IFNDEF STATIC}
  zglLoad( libZenGL );
  {$ENDIF}
  // For loading/creating your own options/profiles/etc. you can get the path to the user home
  // directory, or to the executable file (does not work on GNU/Linux).
  DirApp  := u_CopyStr( PChar( zgl_Get( DIRECTORY_APPLICATION ) ) );
  DirHome := u_CopyStr( PChar( zgl_Get( DIRECTORY_HOME ) ) );

  // Create a timer with an interval of 1000ms.
  timer_Add( @Timer, 1000 );

  // Register the procedure that will be executed after ZenGL initialization.
  zgl_Reg( SYS_LOAD, @Init );
  // Register the render procedure.
  zgl_Reg( SYS_DRAW, @Draw );
  // Register the procedure that will get the delta time between the frames.
  zgl_Reg( SYS_UPDATE, @Update );
  // Register the procedure that will be called after ZenGL shuts down.
  zgl_Reg( SYS_EXIT, @Quit );
  
  // Enable usage of UTF-8, because this unit saved in UTF-8 encoding and here used
  // string variables.
  zgl_Enable( APP_USE_UTF8 );

  // Set the caption of the window.
  wnd_SetCaption( '01 - Initialization' );

  // Show the mouse cursor.
  wnd_ShowCursor( TRUE );

  // Set screen options.
  scr_SetOptions( 800, 600, REFRESH_MAXIMUM, FALSE, FALSE );

  // Initialize ZenGL.
  zgl_Init();
End.

Resulting Code

The result is a template for ZenGL projects:

program template;

{$DEFINE STATIC}

{$R *.res}

uses
  {$IFNDEF STATIC}
  zglHeader
  {$ELSE}
  zgl_main,
  zgl_screen,
  zgl_window,
  zgl_timers,
  zgl_utils
  {$ENDIF}
  ;

var
  DirApp  : String; DirHome : String;

procedure Init;
begin
end;

procedure Draw;
begin
end;

procedure Update( dt : Double );
begin
end;

procedure Timer;
begin
  wnd_SetCaption( '01 - Initialization[ FPS: ' + u_IntToStr( zgl_Get( RENDER_FPS ) ) + ' ]' );
end;

procedure Quit;
begin
end;

Begin
  {$IFNDEF STATIC}
  zglLoad( libZenGL );
  {$ENDIF}
  DirApp  := u_CopyStr( PChar( zgl_Get( DIRECTORY_APPLICATION ) ) );
  DirHome := u_CopyStr( PChar( zgl_Get( DIRECTORY_HOME ) ) );
  timer_Add( @Timer, 1000 );
  zgl_Reg( SYS_LOAD, @Init );
  zgl_Reg( SYS_DRAW, @Draw );
  zgl_Reg( SYS_UPDATE, @Update );
  zgl_Reg( SYS_EXIT, @Quit );
  zgl_Enable( APP_USE_UTF8 );
  wnd_SetCaption( '01 - Initialization' );
  wnd_ShowCursor( TRUE );
  scr_SetOptions( 800, 600, REFRESH_MAXIMUM, FALSE, FALSE );
  zgl_Init();
End.