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

[Florian H]

Zitat von xZise:

Und unter welcher Lizenz steht Andorra 2D und der ImgEdit (ich habe mir daraus das Zeichnen der ListView geholt)?

Laut Webseite:

Zitat:

Andorra 2D is open source and licensed under the CPL. Because of incompatibility to the common open source license GPL you may also use Andorra 2D under the GPL or the LGPL.

CPL: http://www.opensource.org/licenses/cpl1.0.php
GPL: http://www.opensource.org/licenses/gpl-license.php
LGPL: http://www.opensource.org/licenses/lgpl-license.php

Such dir eine passende aus

[3_of_8]

Hab das zweite Tutorial, das über die Anzeige von Bildern, nochmal leicht verbessert, basierend auf romis Vorschlägen.

[igel457]

Vielen Dank, ich aktualisiere das.

Könnte vielleicht nochmal jemand hierüber schauen:

Zitat:

Configuring Andorra 2D

Since version 0.4.5, the "src" directory contains a file named "andorra_conf.inc". This file contains all compiler switches available in Andorra 2D. This short article gives an overview over the meaning of those switches.

Using the "andorra_conf.inc"
The changes made in "src/andorra_conf.inc" are applied globally to all projects. If you don’t want this, delete the "andorra_conf.inc" from the "src" directory and create a copy for all your projects. Add this file to your project or add it to its search path. If you want to be sure whether your settings are actually used, you may activate the "TEST"-switch.

Available switches

DO_NOT_INCLUDE_STD_FORMATS
The VCL/LCL graphics format loaders, which are included by default, will be removed from your project, if you activate this switch. The unit "Graphics" will not be needed anymore, significantly decreasing the size of the executable. As a downside graphics formats like "BMP" etc. cannot be loaded anymore. To make this possible, other loaders have to be included. For example "AdBMP", "AdTGA", "AdPNG" (see below), "AdDevIL" (needs the "DevIL"-library) or "AdFreeImage" (needs the "FreeImage"-library).
Another disadvantage is that generating fonts will be disabled. To use fonts in your project, you have to generate the fonts in an external application, store them in a file and load them afterwards.

DO_NOT_INCLUDE_STD_WINDOWMGR
This switch deactivates loading the VCL/LCL window frameworks - Andorra 2D will not use the unit "Forms" anymore. Activate this compiler switch, if you are using other window frameworks like "AdGLFW", "AdSDL" or "AdWin32". If this compiler switch is activated, Andorra 2D cannot be integrated into an existing VCL/LCL application.

DO_NOT_USE_3DNOW
Deactivates the use of the 3DNow!-instruction set extension when running on AMD processors. This extension is available on AMD-Processors and increases the speed of matrix multiplication (which is used quite often in Andorra 2D). Activating the "DO_NOT_USE_ASM" switch includes this switch.

DO_NOT_USE_ASM
This switch removes any assembler code from Andorra 2D. Native pascal is used.

DO_NOT_USE_INTERNAL_PNG
The image loader unit "AdPNG" may use the external library "PNGImage" or an internal loader. The internal loader works in most cases, but still has some problems. This is why this switch is activated by default.

Copyright and license
(c) by Andreas Stöckel Dezember 2008
This tutorial is subject to the GNU Licence for Free Documentation

[3_of_8]

Ganz in Ordnung, ein paar Formulierungen klingen noch etwas holprig und ein paar mal häufen sich ein paar Wörter. Korrektur:

Zitat:

Configuring Andorra 2D

Since version 0.4.5 the "src" directory contains a file named "andorra_conf.inc", which contains all compiler switches available in Andorra 2D. This short article gives an overview over the meaning of those switches.

Using the "andorra_conf.inc"
The changes made in "src/andorra_conf.inc" are applied globally to all projects. If this is not desired, delete the "andorra_conf.inc" from the "src" directory and create a copy for all your projects. Add this file to your project or add it to its search path. If you want to be sure whether your settings are actually used, you can activate the "TEST"-switch.

Available switches

DO_NOT_INCLUDE_STD_FORMATS
The VCL/LCL graphics format loaders, which are included by default, will be removed from your project, if you activate this switch. The unit "Graphics" will not be needed anymore, which significantly decreases the size of the executable. As a downside, graphics formats like "BMP" etc. cannot be loaded anymore. To make this possible again, other loaders have to be included, such as "AdBMP", "AdTGA", "AdPNG" (see below), "AdDevIL" (requires the "DevIL"-library) or "AdFreeImage" (requires the "FreeImage"-library).
Another disadvantage is that generating fonts will be disabled. To use fonts in your project, you have to generate the fonts in an external application, store them in a file and load them afterwards.

DO_NOT_INCLUDE_STD_WINDOWMGR
This switch deactivates loading the VCL/LCL window frameworks - Andorra 2D will not use the unit "Forms" anymore. Activate this compiler switch if you are using other window frameworks such as "AdGLFW", "AdSDL" or "AdWin32". If this compiler switch is activated, Andorra 2D cannot be integrated into an existing VCL/LCL application.

DO_NOT_USE_3DNOW
Deactivates the use of the 3DNow! instruction set extension when running on AMD processors. This extension is available on AMD processors and increases the speed of matrix multiplication (which is used quite often in Andorra 2D). Activating the "DO_NOT_USE_ASM" switch includes this switch.

DO_NOT_USE_ASM
This switch removes any assembler code from Andorra 2D. Native pascal is used.

DO_NOT_USE_INTERNAL_PNG
The image loader unit "AdPNG" may use the external library "PNGImage" or an internal loader. The internal loader works in most cases, but still has some problems. This is why this switch is activated by default.

Copyright and license
(c) by Andreas Stöckel December 2008
This tutorial is subject to the GNU Licence for Free Documentation

Bei "create a copy for all your projects." war ich mir nicht ganz sicher - ist das jetzt eine Kopie für alle Projekte oder eine Kopie für jedes Projekt? Bei ersterem stimmt es so, bei letzterem wäre es "for each of your project" oder einfach "for each project".

[igel457]

Danke, habe das abgeändert.

[Romi]

Hier die Spriteengine:
Ich wollte es noch vor Neujahr fertig haben, deshalb habe ich viel gestern Nacht gemacht. Wenn also jemand Fehler findet, dann sagt bescheidt

Zitat:

Andorra 2D Tutorials
Teil 3 - The Spriteengine


Introduction
Introduction of the Introduction
Finally it's here: The (first) tutorial which will teach you how to use the Spriteengine. In this tutorial we will modify our project from the last tutorial.


What are sprites?
Sprites are objects which are (simply said) able to move independently from other objects (Check out the correspondingWikipedia Article for more information.).
In Andorra 2D, a sprite is an abstract object which is drawable, moveable and collideable. This actions are controlled by an surperior object (which actually is a sprite, too). Sprite do not have to be moveable - they can also be used to display the background.
And even more - you can write whole games using the Spriteengine.

Creating the SpriteEngine
We have used 4 units so far:

• TAdDraw - The Andorra 2D core
• TAdPerformanceCounter - Calculates the FPS and the "Timegap"
• TAdImageList - Holds all the images
• TAdImage - Manages and draws the images

In this tutorial you will learn how to use the object "TSpriteEngine". First of all, you should add the unit "AdSprites" to the uses-List of your program. Declare a new variable named "AdSpriteEngine" of the type "TSpriteEngine".
The following line of code - which should be inserted after the creation of your Imagelist - will create the SpriteEngine:
AdSpriteEngine := TSpriteEngine.Create(AdDraw); As a matter of course you should free this object at the end of your program.

The family of sprites
Warning: If you do not know much about objectorientated programming yet, you should altercate with that first. Otherwise you may not understand everything.

As already mentioned above a sprite is not only used to draw a simple image. It is able to manage something much more abstract (the Spriteengine itself is a good example for that). Thats why there are multiple spriteclasses available. They all have something in common: They are derived from TSprite, the base-sprite-class.

• TSprite
  • TImageSprite
    • TImageSpriteEx
  • TBackgroundSprite
  • TLightSprite
  • TParticleSprite

The baseclass is a "naked" sprite, which literally is not able to do anything but integrating itself into the Spriteengine. TImageSprite already is able to do anything we would want from a sprite: Drawing and animating. Again, TImageSpriteEx is capable of being drawn transparently and can be turned. TBackgroundSprite is (surprise!) to draw a background. TLight and TParticleSprite will be addressed later.

Go, Sprite, Go
We will now get the guy from our last tutorial running across the screen, but this time we'll use a sprite. So get your result from the last tutorial and get started!
We add the creation of the SpriteEngine and the TImageSprite with the name "figure" the initialisation routine:

Delphi-Quellcode:

.
.
AdImageList.Restore;

//create the SpriteEngine
AdSpriteEngine := TSpriteEngine.Create(nil);
AdSpriteEngine.Surface := AdDraw1;

//create TImageSprite
Figure := TImageSprite.Create(AdSpriteEngine);
with Figure do
begin
  //we'll go on here later on
end;

Do not free "Figure" at the end of your program - you would end in a mess of errors. The spriteengine frees the sprites automatically. If you want a Sprite to be free earlier you have to use it's dead routine.

We now have an "empty" sprite, without graphics or animation:

Delphi-Quellcode:

//assign a graphic to the sprite
Image := AdImageList.Find('figur');  
//activate the animation
AnimActive := true;  
//repeat the animation
AnimLoop := true;  
//set the fps the animation should be played at
AnimSpeed := 15;

From the variables we used before (Pattern,StartPt,EndPt,Y,X,XSpeed) is only one left: XSpeed, because all the other ones are part of TImageSprite.


We will now modify the render routine:

Delphi-Quellcode:

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


  AdDraw.ClearSurface(clBlack);
  AdDraw.BeginScene;

  //call all move-procedure of the engine
  AdSpriteEngine.Move(AdPerCounter.TimeGap / 1000);
  //draw all sprite
  AdSpriteEngine.Draw;
  //delete all sprites wich are marked as dead
  AdSpriteEngine.Dead;

  AdDraw1.EndScene;
  AdDraw1.Flip;

  Done := false;
end;

The following things have changed:

• The part, which was responsible for the animation, has completly gone
• Instead of modifying the value of the variable "X" directly, we now modify the X-Position
• The drawing-routine has gone and is replaced by a routine in the spriteengine

We now have to modify the SetLine procedure a bit:

Delphi-Quellcode:

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

The changes made in this part should be clearly understandable.

And now our figure runs across the screen.

Our own spriteclass
Looking at the solution we have so far we have to admit that it is more or less suboptimal. Wouldn't it be better to have a Spriteclass that does all the movement for us? It would be no problem to have several figures moving independently from each other.

Actually this is possible - thats what the spriteengine is for.
So lets declare a class which is derived from TImageSprite or TImageSpriteEx (just as you like). The declaration should take place above the one of TForm1.

Delphi-Quellcode:

type
  TFigure = class(TImageSprite)
    private
    protected
      procedure DoMove(TimeGap:double);override;
    public
      XSpeed:integer;
      constructor Create(AParent:TSprite);override;
      procedure SetLine;
  end;

DoMove, DoDraw...
Lets have a look at what we have so far:
The "public"-part now has a variable named "XSpeed" - which is the same as our previously globally declared "XSpeed" (which should be deleted by the way...).
The procedure SetLine hat now become part of our sprite, too. Again theres an overwritten constructor.
Now we have nearly everthing which belongs to our figure stored in its' own class. But where is the code that cares about the movement? That's what we have "DoMove" for. Andorra 2D provides a set of those "Do"-Methods:

Delphi-Quellcode:

//this is where the movement takes place
procedure DoMove(TimeGap:double);
//this is where we store our code for collisions (later)
procedure DoCollision(Sprite:TSprite; var Done:boolean);
//this is where we the drawing is done (even later ;) )
procedure DoDraw;

Now we have the base frame of a new class called "TFigure". Thats why the variable "Figure" can now be of the type "TFigure".
The only thing left is the implementaion:

Delphi-Quellcode:

{ TFigure }

constructor TFigure.Create(AParent: TSprite);
begin
  inherited;
  //Start at (0;0)
  X := 0;
  Y := 0;
  
  //Set XSpeed to -150
  XSpeed := -150;
end;

procedure TFigure.DoMove(TimeGap: double);
begin
  inherited;

  //the part from the render-procedure
  X := X + XSpeed*TimeGap;
  if ((X > Engine.SurfaceRect.Right) and (XSpeed > 0)) or
     ((X < -96) and (XSpeed < 0)) then
  begin
    SetLine;
  end;
end;

procedure TFigure.SetLine;
begin
  //moves the figure to a new layer
  XSpeed := -XSpeed;
  if XSpeed > 0 then
  begin
    AnimStart := 0;
    AnimStop := 7;
    X := -96;
  end
  else
  begin
    AnimStart := 8;
    AnimStop := 15;
    X := Engine.SurfaceRect.Right+96;
  end;
  Y := Random(Engine.SurfaceRect.Right-96);
end;

We have to change the code in FormCreate to correspond to our new changes. The following Code has to be replaced:

Delphi-Quellcode:

Figure := TImageSprite.Create(AdSpriteEngine);
.
.

Delphi-Quellcode:

Figure := TFigure.Create(AdSpriteEngine);
with Figure do
begin
  Image := AdImageList1.Find('figure');
  AnimActive := true;
  AnimLoop := true;
  AnimSpeed := 15;
  XSpeed := -150;
  SetLine;
end;

Marathon
Lets have more than one figure running across the screen. Delete the declaration of Figure and replace it by the following code:

Delphi-Quellcode:

for i := 0 to 5 do
begin
  with TFigure.Create(AdSpriteEngine) do
  begin
    Image := AdImageList1.Find('figure');
    AnimActive := true;
    AnimLoop := true;
    AnimSpeed := 15;
    XSpeed := -(random(100)+50);
    SetLine;
  end;
end;

Yet six manikin with different speeds run across the screen.

The whole sourcecode is available at:hier.

Homework
You did it until here. But now I'm having a few assignments for you:

• It is possible that some Figures are displayed over another one although it should be behind it. Remove this error! Hint: The class TSprite has a variable "Z" which is to define its position according to the background.
• All figures look the same. Include a few more graphics!

If you have any questions, feel free to contact me at:E-Mail.

Conclusion
You're now able to deal with the spriteengine. The next tutorial will deal with an old DelphiX-demo, in which you move as a ball through a world peopled with other balls. Certainly, we will "upgrade" it a bit.
The last thing I wanted to notice is that I didn't invent the spriteengine. It's a reproduction of the spriteengine of DelphiX - although it has been enhanced.


Copyright und Lizenz
(c) by Andreas Stöckel März 2007

Revision 2: Oktober 2007

This tutorial is licenced under the GNU Free Documentation License

[igel457]

@Romi: Vielen Dank, ich baue das ein.

Übrigens: Ich habe das versprochene Bugfixrelease 0.4.5.1 hochgeladen.

Die wichtigste Änderung ist, dass die XML-Bibliothek nun keine Dateien mehr unbenutzbar macht.

[Romi]

Zitat von igel457:

Übrigens: Ich habe das versprochene Bugfixrelease 0.4.5.1 hochgeladen.

Die wichtigste Änderung ist, dass die XML-Bibliothek nun keine Dateien mehr unbenutzbar macht.

Also ich habe die jetzt getestet. Und irgentwie hat das DefaultParticle immer noch keine "LifeTime" Eigenschaft, obwohl das im Tutorial ausdrücklich erwähnt wird.

Oder bin ich einfach nur blind?

[igel457]

Hast du DefaultParticle auch entsprechend gecastet? Schau dir mal die SimpleParticle Demo an. Standardmäßig ist default Partikel vom Typ "TAdStdParticle":

Delphi-Quellcode:

with partengine.DefaultParticle as TAdStdParticle do
  LifeTime := 0.5;

[3_of_8]

Romi: sprite engine, nicht Spriteengine, außerdem hast du vergessen, "hier" zu übersetzen und auch steht da noch "Copyright und Lizenz" ganz unten. Genauer hab ichs mir jetzt ned durchgesehen.