Andorra 2D [Ver. 0.4.5.1, 31.12.08]

[igel457]

Andorra 2D

Was ist Andorra 2D?
Nein, Andorra 2D hat nichts mit dem kleinen europäischen Staat "Andorra" zu tun. Wie das "2D" im Namen auch schon erraten lässt, handelt es sich um eine 2D Engine. Diese wird für Delphi und Lazarus (Freepascal) entwickelt und zwar um das bekannte und oft verwendete DelphiX abzulösen (was an DelphiX nicht so toll ist lest ihr am besten hier). Andorra 2D hat einen ähnlichen Aufbau wie DelphiX - das Spriteengineinterface ist sogar zu 99% das Gleiche.

Features
Was ist nun das Besondere an Andorra 2D?
- Hardwarebeschleunigung
- Verwendung von Plugins zur Grafikdarstellung wodurch OpenGL, DirectX oder sogar die GDI mit Andorra 2D verwendet werden können
- Integrierte und beschleunigte Spriteengine
- Integrierte Zoomfunktion in der Spriteengine
- Modularer aufbau von den Loadern für Texturformate, es können einfach eigene Hinzugefügt werden
- orthogonale und perspektivische Projektionsmatrix
- Integration von 3D-Modellen (die Loader sind noch nicht geschrieben)
- Schnelle Partikelsysteme
- Ausnutzung von Multi-Core CPUs
- Lichter
- Shadersupport (Cg und HLSL)
- Einfaches Surface-System
- Einfaches Scenenmanagement
- Videowiedergabe mit MPEG2 Support
- Verwendung von mehreren "Windowframeworks", wodurch Unabhängikeit von der VCL/LCL erreicht wird.
- Clipping/Splitscreens
- 2D Physikengine mit Newton
- Integriertes "Hardware Canvas"
- Mächtiges, voll Skinbares GUI-System
- Nicht überladen - man wird nicht zum benutzen bestimmter Features gezwungen (wie zum Beispiel Datenpackages, wie dies in anderen Engines der Fall ist)
- Opensource, entweder unter der CPL oder der GPL verwendbar
- Mächtiges Bundle von Editoren und Tools
- Deutsche Tutorials
- Viele Demos
- Und natürlich die Banalitäten, die man sich von einer 2D-Engine so wünscht: Rotation, Additives Zeichnen, Skalierung, BitBlt, Texturzugriffe et cetera

Da die Plugins nur um die Basisfunktionalitäten der Grafikschnittstellen Wrapen, könnte man die Plugins theoretisch für eine Hybrid 3D-Engine verwenden

Mehr Infos...
...sowie Tutorials und weitere Links...
gibt es auf der Website: http://andorra.sourceforge.net/
Dort findet ihr auch Demos, Tutorials und Screenshots...

Wenn ihr Fragen, Kritik oder Anregungen habt, dann könnt ihr diese entweder hier oder bei SourceForge posten.

Downloads:
Momentan gibt es die Version 0.4.5. Einen Überblick über alle Downloads gibt es hier.

Das Package mit allen Demos, Prerequisiten und Binaries gibt es in der neusten Version hier:
Andorra 2D All-In-One-Package 23MB

Tutorials:
Die Tutorials gibt es nicht nur auf der Website, sondern auch in der DP. Allerding möchte ich betonen, dass die Tutorials auf meiner Website aktueller sind. Ich kann meine eigenen Tutorials hier nämlich nicht mehr bearbeiten (@Daniel: dringend umändern!). Hier ist eine kleine Liste, wobei die Sterne die Schwierigkeit darstellen:
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngTutorial 1 - Installieren und Initialisieren
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngAndorra 2D über CVS aktualisieren
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngTutorial 2 - Das erste Bild
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngTutorial 3 - Die Spriteengine
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngPartikelsysteme
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngDer Canvas
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngDas GUI-System
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pnghttp://andorra.sourceforge.net/img/star2.pngAndorra 2D und Lazarus
http://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star.pnghttp://andorra.sourceforge.net/img/star2.pngÜber Windowframeworks

FAQ:
Eine Sammlung oft gefragter Fragen findet sich hier:
http://andorra.sourceforge.net/index.php?section=FAQ

Wichtig:
Falls ihr ein Programm mit Andorra 2D geschrieben habt/daran schreibt, dann wäre es schön wenn ihr mir Bescheid sagen könnt. Dann bekomme ich nämlich mal einen Überblick, wer die Bibliothek nun überhaupt verwendet und außerdem kann ich auf meiner Website Screenshots von eurem Projekt einfügen und auch auf eine eventuelle Website eures Projektes verlinken.

Über diesen Thread:
Bitte schreibt hier nur Wünsche oder Anregungen herein, die direkt mit der Engine zu tun haben. Wenn ihr eine Frage über die Anwendung in eurer Anwendung habt, dann macht am besten einen eigenen Thread im Multimedia-Teil auf, bei dem ihr "[Andorra 2D]" vor den Titel schreibt.

Danke für euer Interesse,
Andreas

[igel457]

Nachdem ich noch ein paar Probleme behoben habe, läuft jetzt auch die Videoplayer-Demo zum großen und ganzen untern Linux (aktuelle CVS-Version). Einzig der "Pause"-Knopf will noch nicht so, da TThread.Suspend unter Linux nicht implementiert ist. Als Beiweis habe ich einen kleinen Screenshot angehängt.

Es wird in den nächsten Tagen ein "neues" Release (sowas wie 0.4.6) geben, das einige kritische Probleme (wie zum Beispiel den Bug in der XML-Klasse) behebt.

[Romi]

Zitat von igel457:

Es wird in den nächsten Tagen ein "neues" Release (sowas wie 0.4.6) geben, das einige kritische Probleme (wie zum Beispiel den Bug in der XML-Klasse) behebt.

Das ist schön zu hören. Was mich interessieren würde, was ist mit der Particle Engine los? Sind da einfach nur Änderungen vorgenommen worden und das Tutorial passt nicht mehr ganz darauf, oder wird da gerade gearbeitet und Sachen fehlen?

[3_of_8]

Gibt es denn keine andere Möglichkeit, den Thread anzuhalten? Ein Pause-Flag in die Klasse, das der Thread in jedem Schleifendurchlauf überprüft und nur dann weiter abspielt. wenn es False ist?

[igel457]

Zitat von Romi:

Das ist schön zu hören. Was mich interessieren würde, was ist mit der Particle Engine los? Sind da einfach nur Änderungen vorgenommen worden und das Tutorial passt nicht mehr ganz darauf, oder wird da gerade gearbeitet und Sachen fehlen?

Ich schätze mal, dass das alles von dem Fehler in der XML-Bibliothek kommt. Ich konnte sonst noch keine Probleme mit der Partikelengine feststellen. Wenn du mal in die Demo "SimpleParticles" oder so ähnlich schaust, wirst du feststellen, dass ich auch dort die Eigenschaften des Partieklsystems verändere. Aber ich kümmere mich nochmal darum.

Zitat von 3_of_8:

Gibt es denn keine andere Möglichkeit, den Thread anzuhalten? Ein Pause-Flag in die Klasse, das der Thread in jedem Schleifendurchlauf überprüft und nur dann weiter abspielt, wenn es False ist?

Genau das hatte ich vor. Das ist sowieso schöner, da das "Suspend" potenziell gefährlich ist.

[Romi]

Ich finds super, wie du dich um dein Projekt kümmerst. Kann man dir vllt. irgentwie helfen? Ich mache 2009 mein Abi in Englisch und Informatik, willst du vllt. die Tutorials übersetzt haben, oder sowas?

[igel457]

Das Suspend habe ich jetzt aus AdVideoTexture.pas entfernt, jetzt sollte das auch mit Linux funktionieren.

Das Particelsystem habe ich mir nochmal angeschaut, konnte aber keine Fehler entdecken.

Zitat von Romi:

Kann man dir vllt. irgentwie helfen? Ich mache 2009 mein Abi in Englisch und Informatik, willst du vllt. die Tutorials übersetzt haben, oder sowas?

Danke für das Lob. Das Übersetzten der Tutorials wäre super! Das würde dem Projekt helfen. Wenn du damit Anfangen willst kannst du mir ja nochmal eine PN schicken oder mich im ICQ anschreiben. Die Tutorials sind übrigens in einfachem BB-Code geschrieben. Die aktuellen Tutorials gibt es auf dem Server zum herunterladen:
Z.B.: http://andorra.sourceforge.net/tutots/cvstutot1ger.bb

Ich selbst habe leider keine Zeit mich auch noch um das schreiben der Tutorials auf Englisch zu kümmern, von daher wäre das wirklich toll.

[3_of_8]

Mit den Übersetzungen hab ich auch irgendwann mal angefangen aber es dann wohl wieder vergessen... Seis drum, mir war sowieso grad langweilig, ich hab mal den verlinkten Text übersetzt, grobe Fehler dürften keine drin sein, ich habs dir mal per PN geschickt.

Im Übrigen fehlt in der deutschen Version (und daher auch in meiner Übersetzung, weil ich mir nicht sicher war, wie die Syntax für URLs ist) der Link zu TortoiseCVS.

[Romi]

Jo gut, mit dem war ich auch gerade fast fertig

Wenn es okay für dich ist, werde ich das beste aus beiden Versionen nehmen.

Was mir auch aufgefallen ist, das neue ToroitseCVS sieht ganz anders aus als auf den Screenshots. Stört aber nicht wirklich, die Felder sind fast die gleichen.

Edit:
So, das wäre meine Version. Ich habe nur ein paar Dinge ausgetauscht, die sich für mich komisch angehört haben.

Zitat:

Checking out Andorra 2D with CVS

I thought having a short guidance for getting the latest version of Andorra2D would be a huge advantage, as it took me some time to figure it out. So here it is.

It's a precondition to have a CVS client which is able to fetch the files from the repository. I chose TortoiseCVS. It integrates into the Explorer's context menu and even allows creating a repository of your own. It can be found here.

After downloading and installing the application you should create an empty folder in which the files are to be stored. Open this folder and choose "checkout" in the context menu.

http://andorra.sourceforge.net/tutots/cvs1.png

Now the files for the repository are requested. These are shown in picture 2 using the example of Andorra. The username used is Anonymous and the password is empty. Thereby you only have read-only access. Only registered administrators of the project have writing privileges via SSH.

http://andorra.sourceforge.net/tutots/cvs2.png

Clicking OK starts the process. The minimal output is shown on the following picture.

http://andorra.sourceforge.net/tutots/cvs3.png

If files change now, they are shown in green colour with a U for update. That's it. If you want to bring Andorra up-to-date in the future, you only have to go to the directory and click "Update" or "Refresh CVS locally" in the context menu.

http://andorra.sourceforge.net/tutots/cvs4.png

I hope I was able to clarify some questions with this.

Greetings,
Codewalker (Thomas Hummes)
Translation by 3_of_8 (Manuel Eberl)

[igel457]

Hallo,

Romi, kannst du mir den BB-Code von dem geposteten Tutorial schicken? Dann baue ich das sofort ein.

Um auf die anderen Tutorials zuzugreifen, einfach cvstut1ger.bb durch so etwas wie tut1ger.bb etc. ersetzten. Der Dateiname ist derselbe wie der im bb-Parameter des PHP-Scripts angegebene.

Bevor ich es vergesse, der Setup-Dialog läuft nun auch einwandfrei unter Linux. Hab davon auch noch einen Screenshot angehängt. Mit der aktuellen CVS-Version bin ich übrigens äußerst zufrieden: Hab das ganze einfach unter Linux als Annonymous ausgecheckt, AndorraOGL.lpi geöffnet, auf kompilieren geklickt, die erzeugte "AndorraOGLLaz.dll" zu "AndorraOGLLaz.so" umbenannt, VideoPlayer.lpi geöffnet, F9 gedrückt, fertig. Das ganze setzt natürlich voraus, dass Acinerella installiert ist. Auch der Pauseknopf funktioniert nun so, wie er soll.

[3_of_8]

Romi, könntest du mir bitte die "Dinge, die dir komisch vorgekommen sind" mitteilen? Ich arbeite immer daran, mein Englisch zu verbessern, und ich dachte zwar, dass ich keine Fehler drinhatte, aber ich kann mich natürlich auch irren.

Weil ich momentan zu viel Freizeit habe (bzw. keine Lust auf das, was ich eigentlich zu tun hätte), hab ich gleich noch das nächste übersetzt:

Andorra 2D tutorials
Part 2 - The first graphic


Introduction
In the last tutorial you have learned how to initialise Andorra 2D. The result was a black window. However, we could have achieved this with much less effort. Therefore we now continue with our sample programme - we load an image and display it.

The image list
What we need first of all is a so-called "ImageList", which conveniently stores all images that have been loaded into it.
Now we need a variable of the type "TAdImageList" which we call "AdImageList" and create in FormCreate. Note that the list may only be created after calling AdDraw.Initialize. So we continue writing below the line "Application.OnIdle := Idle":

Code:

AdImageList := TAdImageList.Create(AdDraw);

Now we want to add a image to the list. This is done by the following code:

Code:

with AdImageList.Add('image') do //A image called 'image' is added to the list.
begin
  Texture.LoadGraphicFromFile('texture.bmp'); //A image is loaded into the texture
end;
AdImageList.Restore; //To be explained later

The Imagelist's function "Add" adds a image of the type "TAdImage" with the corresponding name and returns it.

Why does this "TAdImage" now have a sub-object "Texture" again? Are an image and a texture not the same? As the following picture shows, this is not quite true in Andorra2D...
http://andorra.sourceforge.net/tutots/image.png
The image, the object we just added to the image list, that is, is merely some kind of base frame on which the texture is painted. So the "Image" or "Picture" is just a canvas whereas the texture is what is painted on it.

Now another uncertainty has to be clarified: The job of the procedure "Restore". When the image list's function "Restore" is being called, it just calls the "Restore" function of each image. Therefore the following code would do the same:

Code:

with AdImageList.Add('image') do //An image called 'image' is added to the list.
begin
  Texture.LoadGraphicFromFile('texture.bmp',false,clNone); //A texture is loaded into the image without transparency.
  Restore;
end;

However, this method is somewhat laborious when many entries are added to the image list.
Now it only has to be said what this "Restore" does. Let us remember the image mentioned earlier: The image is just the base frame on which the texture is painted. Now the base frame cannot know the size of the texture we loaded. Therefore the base frame is recreated with the appropriate size when the function "Restore" is called and according links are placed. When one forgets calling "Restore", an error message is the most likely result.


Loading the images
The texture provides the following procedure to load and save images:

Code:

procedure LoadFromStream(AStream:TStream);
procedure SaveToStream(AStream:TStream);
procedure SaveToFile(AFile:string);
procedure LoadFromFile(AFile:string);

procedure LoadGraphicFromFile(AFile:string;Transparent:boolean;TransparentColor:TColor);
procedure LoadFromGraphic(AGraphic:TGraphic);

Only the last two methods are relevant for loading graphics directly. The first few write the texture in a file format of Andorra 2D and are not suitable for loading "normal" graphic files.
"LoadFromGraphic" gets the transparency parameters directly from the loaded graphic. By default, Andorra 2D can load all standard graphics formats of the VCL - *.bmp (BItmap), *.dib (Device Independend Bitmap) and *.wmf (Windows Meta File) that is. To load other formats, appropriate loader libraries have to be added to the uses clause. These libraries add themselves to a list in "AdDraw" on initialisation. Andorra 2D can then load these formats and (if implemented accordingly) save them, too. To load PNG images, the unit "AdPNG" has to be added to the uses clause, for JPEG images the unit "AdJPEG". For loading the images, other libraries are needed in most cases. These have to be installed independently from Andorra 2D. For the PNG format the library "PNGDelphi" (http://pngdelphi.sourceforge.net/) is needed.

Rise the curtain
Now we are only a small step away from displaying our first image on the screen. The following line, which we add to the procedure "Idle" between "BeginScene" and "EndScene", does this.

Code:

AdImageList.Find('image').Draw(AdDraw,0,0,0);

Now what do these four parameters of the procedure "Draw" mean? Here AdDraw is the so-called "surface" which is the image is painted on. The next two parameters specify the position on the screen, at which the image is to be painted. The third parameters specifies the so-called "PatternIndex", which handles animations, of which more later.

Now there is not only the function "Draw" alone to draw images, this would be fairly little. The TAdImage object also provides these other procedures:
add

Code:

//Simplest method for drawing
procedure Draw(Dest:TAdDraw;X,Y,PatternIndex:integer);

//Draw an image stretched
procedure StretchDraw(Dest:TAdDraw;const DestRect:TAdRect;PatternIndex:integer);
//Draw an image stretched and with a certain alpha value (from 0 like fully transparent to 255 like completely opaque)
procedure DrawAlpha(Dest: TAdDraw; const DestRect: TAdRect; PatternIndex: Integer; Alpha: Integer);
//Draw an image stretched with additive colour blend and a certain alpha value (from 0 like fully transparent to 255 like completely opaque)
procedure DrawAdd(Dest: TAdDraw; const DestRect: TAdRect; PatternIndex: Integer; Alpha: Integer);
//Draw a stretched image completely black and with a certain alpha value (from 0 like fully transparent to 255 like completely opaque)
procedure DrawMask(Dest: TAdDraw; const DestRect: TAdRect; PatternIndex: Integer; Alpha: Integer);

//Draw an image rotated. Angle is a value from 0 to 360 degrees. CenterX and CenterY denote the centre of the rotation. The two values range from 0 to 1, so 0.5 and 0.5 are exactly the centre of an image.
procedure DrawRotate(Dest: TAdDraw; X, Y, Width, Height: Integer; PatternIndex: Integer; CenterX, CenterY: Double; Angle: Integer);
procedure DrawRotateAdd(Dest: TAdDraw; X, Y, Width, Height: Integer; PatternIndex: Integer; CenterX, CenterY: Double; Angle: Integer; Alpha: Integer);
procedure DrawRotateAlpha(Dest: TAdDraw; X, Y, Width, Height: Integer; PatternIndex: Integer; CenterX, CenterY: Double; Angle: Integer; Alpha: Integer);
procedure DrawRotateMask(Dest: TAdDraw; X, Y, Width, Height: Integer; PatternIndex: Integer; CenterX, CenterY: Double; Angle: Integer; Alpha: Integer);

//Similar to StretchBlt from the Windows GDI. Draws a certain part of the image magnified or downscaled.
procedure DrawEx(Dest:TAdDraw; SourceRect,DestRect:TAdRect;CenterX,CenterY:integer;Angle:Integer;Alpha:Integer;BlendMode:TAd2dBlendMode);

A more detailed description can be found in the documentation:
http://andorra.sourceforge.net/docs/...stomImage.html

You best try these methods on our sample image. However, I will explain some of them in the tutorials. As you might have noticed, Andorra 2D uses its own types such as "TAdRect", which are located in the unit "AdTypes". Therefore the VCL unit "Types" and "Windows" do not have to be used.


Fullscreen
Many games run fullscreen. You can also easily set it up in Andorra 2D. FOr this you only have to navigate to the "OnCreate" method of Form1. Add the following lines before "AdDraw.Initialize":

Code:

with AdDraw.Display do
begin
  Width := 800;
  Height := 600;
  BitDepth := ad32Bit; //The colour depth. The values "ad16Bit" and "ad32Bit" are allowed here.
  DisplayMode := dmFullscreen;
end;

Note that the graphic output of the AdDraw has to be on a TForm or the fullscreen display will not work.

And now your Andorra 2D application already runs fullscreen. However, you have to ensure that both your monitor and your graphics card support the specified resolution. There is a minor trick with which you can achieve fullscreen without having to change the resolution. Instead of the above lines just write:

Code:

BorderStyle := bsNone;
Top := 0;
Left := 0;
Width := Screen.Width;
Height := Screen.Height;

With this only the size of your form is changed.

Important: With the first method, it is tried to run the programme in a real overlay fullscreen mode. This means that the graphics output is a great deal faster because control elements of other applications are not drawn anymore. With the second method the window only covers all the others, so not as many FPS can be reached.

Movements and animations
You best delete all changes from the programme which you have made in this tutorial thus far.

Now we want to have an animated figure run across the screen. As soon as it has reached one edge of the screen, it should run back on an arbitrary Y position.
For this we first need the image of the animated figure - which looks like this:
http://andorra.sourceforge.net/tutots/pattern.png
As we see, this image is effectively constructed like a filmstrip. To show a part of the animated, only a part of the texture is drawn.
You might wonder why we don't have a separate image file for each step of the animation now, (also called frame or pattern) but this would simply be inefficient because it is better for the graphics card to manage one texture the size of 512x512 than many small ones the size of 128x128.

The image of the figure can be downloaded here. By the way, it originates from Reiner's Tilesets. You can find many figures, objects and a lot more for use in 2D games there.

First we have to load the image with the animations into the engine. This is done almost like we did before:

Code:

AdImageList := TAdImageList.Create(AdDraw);
with AdImageList.Add('figure') do
begin
  Texture.LoadGraphicFromFile('boy.bmp',true,clFuchsia);  //This time the image is loaded transparently
  PatternWidth := 96;
  PatternHeight := 96;
end;
AdImageList.Restore;

With PatternWidth and PatternHeight the height and width of a frame are set, in our case to 96. By calling the "Restore" instruction, Andorra 2D creates some kind of map on which stores the number and position of each frame. In fact, Andorra counts from left to right and then from up to down. Also, the numbering starts from zero, as shown on the picture above.

If you now want to draw a single frame from the animation, the "PatternIndex" of the drawing function comes into play. Here you can simply specify the number of the frame and it is drawn.

But we wanted to have the figure run across the screen, so we take care of the animation first. For this we need a variable of the type Single or Double. You will see later why it cannot just be a simple Integer. So we add a variable "Pattern" to the variable declarations in the interface clause of the programme so that the line looks vaguely like this:

Code:

var
  Form1: TForm1;
  Pattern:single;

In "Idle" we now increment Pattern in each step and redraw the figure afterwards. We also have to check if the pattern exceeds the pattern number as the case may be and reset it to zero if it does.

Code:

Pattern := Pattern + 1;
if Pattern >= AdImageList.Items[0].PatternCount-1 then Pattern := 0;
AdImageList.Items[0].Draw(AdDraw,0,0,round(Pattern));

However, upon executing one can see that the animations happens far too fast. The rendering loop is executed up to 5000 times in a second and the pattern is therefore incremented by 5000. Of course, instead of +1 we could now write +0.001, for example, which would cause the animation to run more slowly. However, we then have to problem addressed in the first tutorial, the animation does not run at the same speed on every PC. To avoid this problem, there is another object in Andorra 2D: The so-called "TAdPerformanceCounter" which can be found in the unit "AdPerformanceCounter". So we declare a new variable of the type "TAdPerformanceCounter" called "AdPerCounter", create an instance of the class in "FormCreate" and free it again in FormDestroy as we have done it with all the other objects, too.
We now write "AdPerCounter.Calculate" fairly at the beginning of the "Idle" procedure. With this, the object calculates the lapse of time between procedure runs, apart from that the well-known FPS (frames per second), which you might know from some games and which are an importand performance indicator, are calculated. With the elapsed time in milliseconds, which is stored in the variable "AdPerCounter.TimeGap", we can now create an animation which runs at the same speed on almost all PCs in the world, like this:

Code:

AdPerCounter.Calculate;
Pattern := Pattern + 15 * (AdPerCounter.TimeGap / 1000);

15 is the number of frames per second with which the animation runs here. Upon executing the animation should now run nicely slowly and at an equal speed on every computer.

It was our goal to move the figure across the screen. But apart from being animated nicely now, it lacks movement. Now we first need a handful of new variables, which we declare near the others:

Code:

StartPt,EndPt:integer; //The animation's start and end pattern
Y,X:single; //The figures X and Y position
XSpeed:single; //The velocity in X direction

To move the figure we have to extend the "Draw" routine a bit.

Code:

AdImageList.Find('figure').Draw(AdDraw,round(X),round(Y),round(Pattern));

Now the figure is drawn at the position X and Y. To move it, we write the following above the drawing function:

Code:

X := X + XSpeed * (AdPerCounter.TimeGap / 1000);

Furthermore the animation should only range from "StartPt" to "EndPt", which is why we modify the if statement a bit:

Code:

if Pattern >= EndPt then Pattern := StartPt;

Now we just need a procedure to handle the figure's change of direction. We call it "SetLine", because the figure's Y position is also changed. "SetLine" should be declared within TForm1.

Code:

procedure TForm1.SetLine;
begin
  //Reverse the direction
  XSpeed := -XSpeed;
  
  if XSpeed > 0 then
  begin
    StartPt := 0;
    EndPt := 7;
    X := -96;
  end
  else
  begin
    StartPt := 8;
    EndPt := 15;
    X := ClientWidth+96;
  end;
  
  //Set the Y position
  Y := Random(ClientHeight-96);
end;

Apart from that we need the following line in the "Idle" procedure to call the procedure when the figure leaves the edge of the screen:

Code:

if ((X > ClientWidth) and (XSpeed > 0)) or 
   ((X < -96) and (XSpeed < 0)) then SetLine;

Now we only have to set the XSpeed and call the procedure "SetLine" for the first time in "FormCreate":

Code:

XSpeed := -150;
SetLine;

And now our figure runs across the screen upon execution.

The source code
As always, the source code as a reference:

Code:

unit Main;

interface

uses
  Windows, Dialogs, SysUtils, Graphics, Classes, Forms, AdDraws, AdClasses, AdTypes,
  AdPerformanceCounter;

type
  TForm1 = class(TForm)
    procedure FormCreate(Sender: TObject);
    procedure FormDestroy(Sender: TObject);
    procedure FormResize(Sender: TObject);
  private
    { Private-Deklarationen }
  public
    AdDraw:TAdDraw;
    AdPerCounter:TAdPerformanceCounter;
    AdImageList:TAdImageList;
    procedure Idle(Sender:TObject;var Done:boolean);
    procedure SetLine;
    { Public-Deklarationen }
  end;

var
  Form1: TForm1;
  Pattern:single;
  StartPt,EndPt:integer;
  Y,X:single;
  XSpeed:single;

implementation

{$R *.dfm}

procedure TForm1.SetLine;
begin
  XSpeed := -XSpeed;
  if XSpeed > 0 then
  begin
    StartPt := 0;
    EndPt := 7;
    X := -96;
  end
  else
  begin
    StartPt := 8;
    EndPt := 15;
    X := ClientWidth+96;
  end;
  Y := Random(ClientHeight-96);
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  ReportMemoryLeaksOnShutdown := true;
  AdPerCounter := TPerformanceCounter.Create;

  AdDraw := TAdDraw.Create(self);
  AdDraw.DllName := 'AndorraDX93D.dll';

  if AdDraw.Initialize then
  begin
    Application.OnIdle := Idle;
    AdImageList := TAdImageList.Create(AdDraw);
    with AdImageList.Add('figure') do
    begin
      Texture.LoadGraphicFromFile('boy.bmp',true,clFuchsia);
      PatternWidth := 96;
      PatternHeight := 96;
    end;
    AdImageList.Restore;

    XSpeed := -150;

    Randomize;
    SetLine;
  end
  else
  begin
    ShowMessage('Error while initializing Andorra 2D. Try to use another display '+
                'mode or another video adapter.');
    Close;
  end;
end;

procedure TForm1.FormDestroy(Sender: TObject);
begin
  AdImageList.Free;
  AdPerCounter.Free;
  AdDraw.Free;
end;

procedure TForm1.Idle(Sender: TObject; var Done: boolean);
begin
  if AdDraw.CanDraw then
  begin
    AdPerCounter.Calculate;
    Caption := 'FPS:'+inttostr(AdPerCounter.FPS);

    Pattern := Pattern + 15*AdPerCounter.TimeGap/1000;
    if Pattern >= EndPt then Pattern := StartPt;

    X := X + XSpeed*AdPerCounter.TimeGap/1000;
    if ((X > ClientWidth) and (XSpeed > 0)) or 
       ((X < -96) and (XSpeed < 0)) then SetLine;


    AdDraw.ClearSurface(clBlack);
    AdDraw.BeginScene;

    AdImageList.Find('figure').Draw(AdDraw, round(X), round(Y), round(Pattern));
    AdDraw.EndScene;
    AdDraw.Flip;

    Done := false;
  end;
end;

end.

Conclusion
Now we already have created an animated figure, but the whole thing still was fairly pedestrian. Because of that we will take a look at the a solution integrated into Andorra 2D in the following tutorials: The so-called SpriteEngine. With its help one can programme all kinds of games without much effort.

Copyright and licence
(c) by Andreas Stöckel January 2007
Translation by 3_of_8 (Manuel Eberl)

Revision 2: October 2007
Revision 3: December 2007

The content of this tutorial is subject to the GNU Licence for free documentation.