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

[Neutral General]

Hi,

Grad nur 2 Sachen die mir in den ersten paar Zeilen deiner Übersetzung aufgefallen sind:

1.

Zitat:

we load an image and display it.

2.

Zitat:

Are an image and a texture not the same?

Bin mir da nicht sicher.. Es klingt komisch. Weiß aber auf Anhieb auch nichts Gutes.

[igel457]

Wie gesagt, es wäre super, wenn ihr den BB-Code anhängen könntet, damit ich davon was habe. Ich kann leider eure Posts nicht editieren und den BB-Code kopieren.

Aber schonmal Danke!

[Matze]

OT: Dann zitiere ihn doch.

[igel457]

Zitat von Matze:

OT: Dann zitiere ihn doch.

Bestechende Antwort! Daran habe ich nicht gedacht. Die Tutorials sind hochgeladen und verlinkt.

Nochmal Danke!

[3_of_8]

Ich weiß, ich weiß... zu viel Freizeit...

Zitat:

Andorra 2D GUI
Part 1 - Using the GUI system


Introduction
http://andorra.sourceforge.net/tutots/guisample.jpg
Virtually all professional games do not use the standard components that Windows offers to build up the user interface. The GUI system should be adapted to the game after all - a simulation of the middle ages does certainly not benefit from higgledy-piggledy Windows XP buttons. Also, it is difficult to display the standard components in a hardware-accelerated way. To give you the possibility of creating consistent GUIs which are fully integrated into your game, Andorra 2D provides a fairly powerful and in most cases sufficient GUI system. This can easily be extended with self-made components and is also fully skinnable.
Please note: Writing such a GUI system is very time-consuming, which is why its development is currently suspended. If you have created new components on your own or wish to extend the system, please send me an e-mail.


Preparations
First you have to create a GUI in the supplied GUI editor, which works in a similar way to Delphi. In the process you should save each form as a separate GUI file. (*.axg, Andorra XML GUI)
Skins can also be created with the supplied skin editor which, however, is still somewhat complicated at the moment. Anyhow, the supplied skin file "sunna.axs" can be modified to achieve the same result.
Apart from that, an Andorra GUI needs a cursor definition file. For this, create an image list with the according cursors with the image list editor and write a simple XML file according to the following example, in which you refer to the individual entries:

Delphi-Quellcode:

<?xml version="1.0" encoding="iso-8859-1"?>
  <set>
    <images source="cursors.ail"/>
    <cursor name="default" src="default">
      <hotspot x="0" y="0"/>
    </cursor>
    <cursor name="wait" src="wait">
      <hotspot x="6" y="11"/>
      <anim start="0" stop="7" speed="25"/>
    </cursor>
    <cursor name="cross" src="cross">
      <hotspot x="8" y="8"/>
    </cursor>    
  </set>

Integration
To use the GUI in a programme now, we first need some units:
The base frame of all GUI components is located in "AdGUI" as well as the implementation of the cursors and the GUI manager. It is important to include the unit "AdComponents", if you use the supplied components. The reason for this is that with including the unit, the corresponding components are registered in the GUI system. If the file is not included, an error message is displayed because the specified components are not registered and therefore cannot be found.
First of all we need an instance of the class "TAdGUI", which takes care of loading, saving, skins and cursors automatically.

Delphi-Quellcode:

AdGUI := TAdGUI.Create(AdDraw); //Instantiating the class
AdGUI.Skin.LoadFromFile('sunna.axs'); //Loading the skin
AdGUI.Cursors.LoadFromFile('cursors.xml'); //Loading the cursor
AdGUI.LoadFromFile('gui.axg'); //Loading the GUI

Important: Commonly made mistakes
- Forgetting the unit "AdComponents"
- Forgetting to include a PNG loader (such as AdPNG, AdDevIL or AdFreeImage), because the standard skin "Sunna" uses the format PNG to save the data.

Of course, "AdGUI" has to be freed in the end. One only has to call the method
AdGUI.Update in the game loop.
Technically, these steps should suffice to display the GUI. However, the emphasis lies on "display" - one can hit the mouse button as hard as one likes, nothing happens. Why would it? After all, mouse and keyboard events have to be passed on to the GUI system first. There are two possibilities for doing this. The first one is the easier one which should be enough in most cases.
We use the class "TAdGUIConnector" from the unit "AdGUIConnector". This loops the events of the AdDraw parent window system through the GUI system. For this, the following steps are necessary:

Delphi-Quellcode:

AdConnector := TAdGUIConnector.Create(AdGUI); //Creating the GUI connector
AdConnector.ConnectEventHandlers(AdDraw.Window); //Linking it to the parent window system

The GUI connector should also be freed upon terminating the programme.
But the GUI connector (still) has a few flaws: One can only link the events to a component of the class "TForm" - if the AdDraw is on a panel, the events have to be passed on manually.
However, this method is not that bad and also has another inherent advantage: Imagine a construction game, in which freely movable windows are on the screen. How can the game know if we clicked on the window or on the game field? Not a problem with the manual linking!

Delphi-Quellcode:

procedure Form1Click(Sender:TObject)
var
  p:TPoint;
begin
  GetCursorPos(p); //Read current cursor position
  p := ScreenToClient(p); //Convert to form-relative coordinates
  if not AdGUI.Click(p.X, p.Y) then //Execute event handling
  begin
   //The game field was clicked
  end;
end;

At this, the "Click" method of the GUI system is simply called, which recursively calls the click methods of all the other elements. When it is detected that the click was indeed on a control element, the "Click" method returns "true".
This works analogously with every other event handler.


Accessing control elements
Now it would be highly convenient if we could access the elements created in the editor in our programme somehow. In the editor, the elements are assigned a name which is stored in the property "Name" - just like in Delphi. The method "FindComponent" of TAdGUI returns the wanted element when given the corresponding name. To access component-specific properties, we only have to cast the result to the according component class.
TAdButton(AdGUI.FindComponent('AdButton1')).Caption := 'Hello!';
Control element events
Our GUI system is still fairly inanimate - we do not react to events such as clicks at all yet.
For that we can simply link procedures to events such as "OnClick". We have to create a procedure that has exactly the same parameters as the event procedure. These can be found out in the code completion. Please note that the declared procedure has to be part of a class. Example:

Delphi-Quellcode:

type
  TForm1 = class(TForm)
    [...]
  private
    procedure AdButtonClick(Sender:TObject);
  public
    [...]
end;

[...]

procedure TForm1.AdButtonClick(Sender:TObject);
begin
  TAdButton(AdGUI.FindComponent('AdButton1')).Caption := 'You clicked me!!';
end;

procedure TForm1.FormCreate(Sender:TObject);
begin
  //Initialise Andorra 2D
  [...]
  //Load GUI
  [...]

  //Assign events
  TAdButton(AdGUI.FindComponent('AdButton1')).OnClick := AdButtonClick;
end;

By the way, this works the same way in the VCL.

Customised components
To create customised components, derive a class from "TAdComponent" and register it in the "initialization" clause of the unit. Along the lines of "Code is worth a thousand words" you best learn how this works by reading the unit "AdComponents". To use your creations in the editor, you have to include the corresponding class there, too.

Extend code with a loaded GUI
Calling "LoadFromFile" usually replaces the whole GUI - this can be avoided with the following code. Please note that you have to include the unit "AdSimpleXML" additionally.

Delphi-Quellcode:

procedure ExpandGUI(afile: string);
var
  elems:TAdSimpleXMLElems;
  xml:TAdSimpleXML;
  j:integer;
  cref:TPersistentClass;

  function SearchFirst(elem:TAdSimpleXMLElem):TAdSimpleXMLElems;
  var
    i:integer;
  begin
    result := nil;
    for i := 0 to elem.Items.Count - 1 do
    begin
      if elem.Items[i].Name <> 'TAdGUI' then
      begin
        result := elem.Items;
        exit;
      end
      else
      begin
        result := SearchFirst(elem.Items[i]);
        if result <> nil then
        begin
          exit;
        end;
      end;
    end;
  end;

begin
  xml := TAdSimpleXML.Create;
  xml.LoadFromFile(afile);
  elems := SearchFirst(xml.Root);
  if elems <> nil then
  begin
    for j := 0 to elems.Count - 1 do
    begin
      cref := GetClass(elems.Item[j].Name);
      if cref <> nil then
      begin
        with TAdComponent(TAdComponentClass(cref).Create(AdGUI)) do
        begin
          LoadFromXML(elems.Item[j]);
        end;
      end;
    end;
  end;
  xml.Free;
end;

Conclusion
This information should help you deal with the GUI system. It is most important to take a look at the properties of the components. Don't be afraid to take a look at the implementation of a component - then emerging questions usually sort themselves out. After all, this is fairly easy in Delphi but also in Lazarus: If you click on an identifier while pressing the CTRL key, you automatically navigate to its declaration.

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

The content of this tutorial is subject to the
GNU Licence for Free Documentation

[Romi]

Zitat:

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.

Eigentlich musst du ja nur meinen mit deinem Text vergleichen, oder was genau meinst du?

Zitat:

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:

Mist. Damit hatte ich auch schon angefangen (und war ca 50% fertig), und dann musste ich bis gerade weg. Wir sollten uns absprechen

Hier noch ein paar Vorschläge:

Zitat:

What we need first of all is a so-called "ImageList"

First of all we need a so-called "ImageList"

Zitat:

and create in FormCreate.

and is created in FormCreate.

Zitat:

The Imagelist's function "Add" adds a image

an Image

Zitat:

Why does this "TAdImage" now have a sub-object "Texture" again?

Ich finde, den Satz kann man nicht direkt übersetzen. Mein Vorschlag:
What is the property "Texture" of "TAdImage"? An image and a texture are the same, aren't they?
The following picture will show you that they're not (at least for Andorra 2D):

Zitat:

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.

The image (the object we just added to the image list) is merely some kind of base frame on which the texture is painted.

Zitat:

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.

The assignment of the procedure "Restore". When the image list's function "Restore" is being called, it just calls the "restore" function of each of it's images.

Zitat:

However, this method is somewhat laborious when many entries are added to the image list.

But this method is a bit circumstantial when adding a lot of images to the list.

Zitat:

Now it only has to be said what this "Restore" does.

The last thing to address is what exactly this "restore"-funtcion does.

Zitat:

When one forgets calling "Restore", an error message is the most likely result.

If you forget to call the "restore"-function you will probably end with an error.

Zitat:

of the VCL - *.bmp (BItmap), *.dib (Device Independend Bitmap) and *.wmf (Windows Meta File) that is.

of the VCL - namely *.bmp (BItmap), *.dib (Device Independend Bitmap) and *.wmf (Windows Meta File).

Zitat:

These libraries add themselves to a list on initialisation.

This libraries will add themselves to a list in the unit AdDraw.

Zitat:

For loading the images, other libraries are needed mostly.

For loading the images, other libraries are needed.


So weit war ich.

[3_of_8]

Ich hab absichtlich das letzte genommen, weil ich vermutet habe, dass du mit dem nächsten weitermachst.

Und, ja, ich habe verglichen, verstehe aber nicht so ganz, was daran seltsam klingt.

[Romi]

Zitat von 3_of_8:

Ich hab absichtlich das letzte genommen, weil ich vermutet habe, dass du mit dem nächsten weitermachst.

Und, ja, ich habe verglichen, verstehe aber nicht so ganz, was daran seltsam klingt.

Ich habe oben noch ein paar Dinge dazugeschrieben. Kannst du dir ja überlegen, ob du sie übernimmst

Ich mache übrigens gerade das Tutorial zur Spriteengine. Also lass da die Finger von

[3_of_8]

Zitat:

What we need first of all is a so-called "ImageList"
First of all we need a so-called "ImageList"

Geht beides.

Zitat:

and create in FormCreate.
and is created in FormCreate.

Der Rest des Satzes ist auch im Aktiv, Subjekt ist "we". Warum also hier Passiv?

Zitat:

The Imagelist's function "Add" adds a image
an Image

Schon gefixt, dank Neutral General

Zitat:

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...]
Ich finde, den Satz kann man nicht direkt übersetzen. Mein Vorschlag:
What is the property "Texture" of "TAdImage"? An image and a texture are the same, aren't they?
The following picture will show you that they're not (at least for Andorra 2D):

Nach Auskunft einer Engländerin versteht sie beides nicht wirklich, aber es sind keine Fehler drin.

Zitat:

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.
The image (the object we just added to the image list) is merely some kind of base frame on which the texture is painted.

Also ob da jetzt ne Klammer is oder ein Einschub, das dürfte doch relativ egal sein.

Zitat:

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.
The assignment of the procedure "Restore". When the image list's function "Restore" is being called, it just calls the "restore" function of each of it's images.

"assignment" klingt irgendwie mehr so nach "Mission, Auftrag".

Zitat:

However, this method is somewhat laborious when many entries are added to the image list.
But this method is a bit circumstantial when adding a lot of images to the list.

Wo ist das Problem mit "However", "laborious" und dem Rest der geänderten sachen?

Zitat:

Now it only has to be said what this "Restore" does.
The last thing to address is what exactly this "restore"-funtcion [sic!] does.
Korrektur: The last thing to address is what exactly this "Restore" function does.
("Restore" ist auch im Source großgeschrieben, IIRC, daher auch hier groß, weil Zitat, Bindestrich weg, ansonsten klingt das in der Tat besser als mein Satz)

Jop, übernehm ich in Korrektur.

Zitat:

When one forgets calling "Restore", an error message is the most likely result.
If you forget to call the "restore"-function you will probably end with an error.
Korrektur: [...]you will probably end up with an error.

Meine Variante ist deutlich förmlicher, ob das jetzt erwünscht ist oder nicht - keine Ahnung. Der Stil im deutschen Original schwankt ja sehr stark zwischen höflich-förmlich und kumpelhaft, und da ich recht nah am Original übersetzt habe, ist das jetzt hier wohl auch so.

Zitat:

of the VCL - *.bmp (BItmap), *.dib (Device Independend Bitmap) and *.wmf (Windows Meta File) that is.
of the VCL - namely *.bmp (BItmap), *.dib (Device Independend Bitmap) and *.wmf (Windows Meta File).

Das dürfte ziemlich äquivalent sein.

Zitat:

These libraries add themselves to a list on initialisation.
This libraries will add themselves to a list in the unit AdDraw.

Hoppala, das mit dem AdDraw habe ich tatsächlich übersehen, aber in deiner Version fehlt dafür das mit dem Programmstart.

Zitat:

For loading the images, other libraries are needed mostly.
For loading the images, other libraries are needed.

Meine Version klingt jetzt im Nachhinein doch etwas seltsam.

[xZise]

Ich habe mir noch nicht die neueste Version geholt, aber funktioniert es jetzt unter Delphi 2009, dass die Grafiken richtig im ImgEdit angezeigt werden?

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

MfG
xZise