Andorra 2D - Tutorial 1 - Installieren und Initialisieren

[igel457]

Das Tutorial befindet sich in der Originalversion hier

Andorra 2D Tutorials
Teil 1 - Initialisieren von Andorra 2D


Was ist Andorra 2D?
Andorra 2D ist eine neue 2D Engine für Delphi, Kylix und Freepascal/Lazarus. Eine 2D-Engine kümmert sich darum, Grafiken in schnellst möglicher abfolge auf den Bildschirm zu bringen, um damit zum Beispiel Spiele entwickeln zu können. Zudem sind mit einer 2D-Engine Effekte möglich, die mit den standard Windows/Linux Grafikfunktionen nicht ohne weiteres möglich wären. Andorra 2D zeichnet sich durch folgende Features besonders aus:

• Verwendung verschiedener Grafikschnitstellen - DirectX oder OpenGL, beides ist möglich.
• Kompatibilität zu DelphiX - "Alte" DelphiX Programme können ohne großen Aufwand in Andorra 2D Anwendungen konvertiert werden.
• 3D-Beschleunigung Alle Grafikoperationen werden mit der 3D-Hardware gezeichnet, was einen enormen Geschwindigkeitsschub bringt.
• Spriteengine Andorra 2D beinhaltet eine Leistungsfähige Spriteengine mit der einfach Spiele erstellt werden können
• Canvas Andorra 2D beinhaltet eine hardwarebeschleunigte Zeichenfläche, die an das Delphi Canvas angelehnt ist.

Weitere Informationen gibt es auch auf der Website des Projekts: http://andorra.sf.net

Herunterladen und Installieren

Schritt 1: Herunterladen
Die aktuelle Version von Andorra 2D finden sie auf der Website unter "Downloads". Dort finden Sie auch eine Liste mit den Delphi/Lazarus Versionen, mit denen Andorra 2D kompatibel ist.

Schritt 2: In das Delphi Verzeichnis kopieren
Kopieren Sie den Ordner "src" in Ihr "lib" Verzeichnis (z.B.: C:\Programme\Borland\BDS\4.0\lib\). Nennen Sie den Ordner in "Andorra" oder ähnliches um.

Schritt 3: Zum Bibliothekspfad hinzufügen
Fügen Sie ihrem Delphi diesen Pfad als Bibliothekspfad hinzu. (Meistens unter Tools/Optionen oder Tools/Umgebungsoptionen)

Nun sollte Andorra 2D eigentlich einsatzbereit sein.

Nur noch ein Wort zu den Bibliotheken, die den fertig kompilierten Demo-Paketen beiliegen:
Die Bibliotheken (AndorraDX93D.dll etc.) wurden mit Turbo Delphi Explorer kompiliert. Wenn Sie diese mit einer anderen Delphiversion verwenden kann es zu Zugriffsverletzungen kommen, da zwischen Host und Bibliothek Objekte ausgetauscht werden und sich deren interner Aufbau über die verschiedenen Versionen hinweg geändert haben kann. Deshalb rate ich Ihnen die Bibliotheken noch mal neu zu kompilieren.

Enthaltne Units
Bevor wir loslegen, hier erst einmal eine Übersicht über alle Units, die im Andorrapacket enthalten sind. Sie können diesen Teil getrost überspringen und zum Nachschlagen nutzen.

• Ad3dObj.pas - Beinhaltet Funktionen und Klassen zum verwenden von 3D-Models (noch nicht fertig).
• AdApps.pas - Beinhaltet eine Klasse, mit der einfach ein Andorra Projekt erstellt werden kann.
• AdBitmap.pas - Beinhaltet die Klasse "TAdBitmap", mit der Bilder in Texturen geladen werden können.
• AdBitmapClass.pas - Beinhaltet die Mutterklasse von "TAdBitmap", die die Daten eines Bitmaps enthält und mit deren Hilfe Pixel des Bitmaps manipuliert werden können.
• AdBitmapEffekts.pas - Beinhaltet Effekte, die auf ein "TAdBitmap" angewandt werden können (Blur etc.) (noch nicht fertig).
• AdCanvas.pas - Beinhaltet die Andorra Zeichenfläche. Diese unit muss eingebunden werden, um auf Konstanten, die in Verbindung mit dem Canvas auftreten zugreifen zu können.
• AdClasses.pas - Beinhaltet die Klassen, die zur komunikation zwischen Hostanwendung und DLL verwendet werden
• AdComponents.pas - Beinhaltet Komponenten zur Verwendung für die GUI. Vergessen Sie nicht diese Unit einzubinden, wenn Sie mit der GUI arbeiten.
• AdContainerts.pas - Beinhaltet einfache Containerklassen (Listen, Hasmaps etc.), die andorraintern verwendet werden.
• AdDLLExplorer.pas - Beinhaltet eine einfache Klasse, mit deren Hilfe nach andorrakompatiblen DLLs gesucht werden kann.
• AdDLLLoader.pas - Beinhaltet eine Klasse, die die Plugindlls lädt.
• AdDraws.pas - Die wichtigste Unit, die das Andorra Hauptobjekt beinhaltet. Die Klassen vereinfachen den Zugriff auf das eigentliche Andorra Plugin interface enorm.
• AdFont.pas - Beinhaltet die Fontklasse, die Bitmapfonts zeichnen kann.
• AdFontFactory.pas - Beinhaltet ein Klasse, die Fonts lädt und Fontobjekte erzeugt.
• AdFontGenerator.pas - Beinhaltet eine abstrakte Oberklasse. Abgeleitete Klassen kümmern sich um das erzeugen von Bitmapfonts.
• AdFontList.pas - Beinhaltet eine Liste, in der Fonts einfach verwaltet und in Dateien gespeichert werden können.
• AdGraphicEx.pas - Beinhaltet eine sehr experimentelle Schnitstelle zu der GraphicEx-Bibliothek.
• AdGUI.pas - Beinhaltet die Basisklassen, von denen GUI-Elemente abgeleitet sind.
• AdGUIConnector.pas - Beinhaltet eine Klasse, die sich darum kümmert, GUI-Objekte mit Formularen zu verbinden.
• AdJPEG.pas - Binden Sie diese Unit ein, um die Möglichkeit zu erhalten, JPEG-Dateien zu laden.
• AdList.pas - Beinhaltet eine abgeleitete Klasse von TList, die kompatibilität zu Delphi 4 schaffen soll (noch nicht fertig).
• AdParticles.pas - Beinhaltet eine Klasse, die sich um die Darstellung von Partikelsystem kümmert.
• AdPerformanceCounter.pas - Beinhaltet eine Klasse, die sich darum kümmert die vergangene Zeit zwischen zwei Frames zu berechnen
• AdPersistent.pas - Beinhaltet eine Ersatzklasse für "TPersistent" aus der Unit "Classes".
• AdPhysics.pas - Beinhaltet eine erweiterte Spriteengine, die sich darum kümmert "Newton Game Dynamics" einzubinden.
• AdPNG.pas - Binden Sie diese Unit ein, um die Möglichkeit zu erhalten, PNG-Dateien zu laden und zu speichern. Sie benötigen die Bilbiothek "PNGImage".
• AdRAWFonts.pas - Diese Unit wird dazu verwendet Bitmapfonts zu laden.
• AdSetupDlg.pas - Beinhaltet eine Klasse, die einen Dialog mit Einstellungen für das TAdDraw Objekt anzeigt.
• AdShapes.pas - Beinhaltet Klasse, die sich um pixelgenaue Kollision zwischen Objekten kümmert.
• AdSimpleCompressors.pas - Beinhaltet einfache Kompressoren, die Bilder in Dateien oder Streams speichern können.
• AdSkin.pas - Beinhaltet Klassen, die sich um das Laden und Zeichnen von Skins für das GUI-System kümmern.
• AdSpriteEngineEx.pas - Beinhaltet eine erweiterte Spriteengine, mit der der Bildschirminhalt gedreht und vergrößert werden kann.
• AdSprites.pas - Beinhaltet das Spriteengine System.
• AdStandardFontGenerator.pas - Beinhaltet eine Klasse, die sich um das generieren von Bitmapfonts mit VCL/LCL Methoden kümmert.
• AdTypes.pas - Beinhaltet Typendeklarationen.
• AdVCLFormats.pas - Beinhaltet Klassen, die sich um das Laden von VCL Grafikformaten kümmert.

Einige dieser Units registeren sich automatisch, sobald sie ein einer Uses-Anweisung stehen. Klassen daraus müssen nicht direkt verwendet werden. Manche dieser Units werden mit dem Einbinden von "AdDraws" automatisch registriert. Diese sind kursiv makiert.

Andorra 2D Initialisieren

Vorbereitungen...
Nun haben Sie Andorra 2D erfolgreich bei sich installiert und nun möchten Sie es garantiert auch ausprobieren. Dazu erstellen Sie eine neue "VCL-Formularanwendung" in Delphi.

Am besten speichern Sie das Projekt erst einmal in einen eigenen Ordner und kopieren die entsprechenden Andorra-DLLs in diesen hinein.

Fügen Sie jetzt folgende Units zur uses Klausel von Form1.pas (der Name kann abweichen, falls Sie die Datei unter einem anderem Namen gespeichert haben) hinzu:

• AdDraws: enthält den Hauptkern
• AdClasses: enthält noch einige Typen- und Klassendeklarationen, sowie Hilfsfunktionen, die oft benötigt werden.
• AdTypes: enthält Typendeklarationen

Die uses-Klausel sollte jetzt ungefähr so aussehen:

Delphi-Quellcode:

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, AdDraws, AdClasses, AdTypes;

Nun müssen Sie erst einmal ein Objekt des Typs TAdDraw deklarieren. Bei TAdDraw handelt es sich um das "Herzstück" von Andorra 2D. Es initialisiert und finalisiert dies Engine und stellt die aktuelle Szene auf dem Bildschirm dar.
Fügen Sie also folgenden Code im "public" Abschnitt der Deklaration von TForm1 ein:
AdDraw:TAdDraw; Nun muss eine Instanz des Objekts in OnFromCreate erzeugt werden. Wählen Sie dazu im Formulardesigner das Form1 aus und doppelklicken Sie im Objektinspektor im Abschnitt "Ereignisse" hinter den Eintrag "OnCreate". Fügen Sie in den darauf hin im Codeeditor folgenden Code ein:

AdDraw := TAdDraw.Create(self); Dies erzeugt eine neue Instanz von TAdDraw. Das "self" ist eine Referenz auf Form1 und teilt der Engine somit mit, dass alle Grafikausgaben auf Form1 stattfinden sollen. Sie können stattdessen auch z.B. ein Panel aus der Objektpalette auf Form1 ziehen und anstatt "self" "Panel1" angeben. Damit landen die Grafikausgaben auf Panel1.

Außerdem muss die nun erzeugte Instanz von TAdDraw am Ende des Programms wieder freigegeben werden (d.h. allen Speicher den Sie belegt wieder für andere Objekte zur Verfügung stellen). Fügen Sie deshalb in das "OnDestroy" Ereignis des Objekts Form1 folgenden Code ein:

AdDraw.Free; Damit wird der Speicher den die Engine verwendet frei gegeben und die Engine selbst finalisiert.

Nun aber wieder zurück zur Initialisierung. Irgendwie müssen wir der Engine mitteilen, welches Plugin (also welche Grafikschnittstelle) sie verwenden soll. Dazu müssen wir den Eintrag "DllName" von AdDraw1 auf den Dateinamen des Plugins setzten. Der Name des Plugins für DirectX9 lautet "AndorraDX93D.dll". Sie können hier auch jedes andere Andorra 2D Plugin verwenden, es muss sich nur im Verzeichnis der Anwendung befinden, zum Beispiel das Plugin "AndorraOGL.dll", welches Andorra mit OpenGL verwendet.

Fügen Sie also die folgende Zeile zu OnCreate hinzu:
AdDraw.DllName := 'AndorraDX93D.dll'; Damit wird automatisch die entsprechende DLL geladen.


Die Initialisierung...
Nun möchten wir Andorra 2D initialisieren. Dies funktioniert über die Funktion mit dem viel versprechendem Titel "Initialize". Diese Funktion versucht Andorra 2D zu initialisieren und gibt wenn dies erfolgreich passiert ist "true" zurück. Also erweitern wir die OnCreate Funktion wieder um ein paar Zeilen...

Delphi-Quellcode:

if AdDraw.Initialize then
begin
  // Hier geht's gleich weiter
end
else
begin
  ShowMessage('Error while initializing Andorra 2D. Try to use another display'+
              'mode or use another video adapter.');
  halt; //<-- Schließt die komplette Anwendung
end;

So weit wären wir schon mal. Wenn das Programm jetzt kompiliert und beim Ausführen keine Fehlermeldung erscheint ist Andorra 2D am laufen. Nur sehen tun wir davon (noch) nichts. Dies ist auch logisch, da noch überhaupt nichts ausgegeben wird.


Juhu, ein schwares Fenster
Nun müssen wir nochmal kurz zur Thorie.
Bei Spielen kommt es darauf an, das sich der Bildschirminhalt ständig ändert. Dazu kann man zu einer Quasiendlosschleife greifen, was dann in Pseudodelphicode so aussehen würde:

Delphi-Quellcode:

repeat
  Berrechne_Bewegungen;
  Zeichne;
  if PressESC then abort := true;
until abort;
Close;

Nachteil dieser Methode ist, dass die CPU-Auslastung auf 100% steigt (und besonders bei Laptops macht sich der Nachteil eines höheren Stromverbrauchs bemerkbar, solche Programme sind also "Akku-Killer"). Die Leistung von CPU und GPU wirkt sich außerdem direkt auf die Anzahl der Schleifendurchläufe in einer Sekunde aus, was unterschiedliche Bewegungsgeschwindigkeiten hervorrufen kann (aber dieses Problem kann recht einfach gelöst werden, wie ich im nächsten Tutorial zeigen werde...)

Eine andere Möglichkeit ergibt sich in der Verwendung einer TTimer Komponente. Hier wird einfach ein Intervall in ms eingestellt und "Enabled" auf true gesetzt. In das Ereigniss "OnTimer" würde man dann folgenden Code schreiben:

Delphi-Quellcode:

Berrechne_Bewegungen;
Zeichne;

Nachteil dieser Methode ist jedoch, dass die Hardware nich vollständig ausgenutzt wird, da das Ereigniss höchstens um die 50 mal die Sekunde ausgelöst wird.

Trotzdem allen "Nachteilen" möchten wir hier auf die erste Methode eingehen. Sie werden sich nun fragen, wo man diese Endlosschleife plazieren sollte. Die Antwort lautet: Bei VCL Anwendungen gar nicht. Denn intern hat jede VCL-Anwendung schon eine Schleife, die ungefähr so aussieht:

Delphi-Quellcode:

while not Application.Terminated do
begin
  Application.ProcessMessages;
  if Done = false then Application.OnIdle; //Stimmt zwar so nicht 100%ig, aber so kann man es sich besser vorstellen.
end;

Wie wir sehen wird jeden Schleifendurchlauf eine Funktion namens "OnIdle" aufgerufen - und mit dieser können wir uns ganz einfach verknüpfen und dort unseren Code hinein schreiben.

Das funktioniert so:
Im "public" Teil der Deklaration von Form1 fügen wir folgende Zeile hinzu:

procedure Idle(Sender:TObject; var Done:boolean); Nun fügen wir folgende Prozedur an unser Programm ein...

Delphi-Quellcode:

procedure TForm1.Idle(Sender: TObject; var Done: boolean);
begin
  if AdDraw.CanDraw then //Wenn überhaupt auf das AdDraw gezeichnet werden kann dann...
  begin
    //auch hier geht's bald weiter.
  end;
  
  Done := false; // Diese Zeile nicht vergessen, sonst wird der Code nur sporadisch ausgeführt.
end;

...und erweitern "OnCreate", an der Stelle wo der Kommentar "hier gehts gleich weiter" steht um folgende Zeile:

Application.OnIdle := Idle; Damit wird das "OnIdle"-Event, welches wir von oben kennen mit unserer "Idle"-Funktion verknüpft.

Widmen wir uns nun der Idle Funktion, sozusagen das Herzstück unseres Programms. Hier landen alle Berechnungen und Zeichenoperationen der Engine.
Also fügen wir folgenden Code ein:

Delphi-Quellcode:

AdDraw.ClearSurface(clBlack); //Füllt die Oberfläche mit schwarzer Farbe

AdDraw.BeginScene;
//Hier müssen spätere Zeichenfunktionen stehen
AdDraw.EndScene;

AdDraw.Flip; //Präsentiert die gezeichneten Dinge auf dem Bildschirm.

Ich denke, die Kommentare sagen das meiste.

Nur noch ein Wort zu dem AdDraw1.Flip. Wer schon mehr mit Delphi und dessen Canvas gearbeitet hat, dem wird auffallen, dass die Ausgabe zu flackern beginnt, wenn viele Grafikoperationen ausgeführt werden. Dies würde auch bei unserer Engine passieren, würden die Grafiksysteme, die dahinter stecken, nicht einen Trick anwenden: Das System verwaltet zwei Speicher. Alle Grafikausgaben landen in Speicher Nr.1. Beim aufrufen der Flip-Funktion wird der Monitor mit den Daten aus Speicher Nr.1 gefüttert. Währenddessen ist nun Speicher Nr.2 zu dem Speicher geworden, in dem die Grafikausgaben landen. Beim nächsten aufrufen von "Flip" wird der Monitor mit den Daten aus Speicher Nr.2 gefüttert und Speicher Nr.1 wird zum Speicher für die Ausgaben. Dieses System nennt sich auch "Double-Buffering". Wer mehr dazu wissen will, sollte mal Wikipedia befragen.

Jetzt aber wieder zurück zu Delphi - wir drücken voller Erwartung die "F9" Taste oder klicken auf den grünen Pfeil in der Symbolleiste - wenn alles gut gelaufen ist sollten Sie ein schwarzes Fenster sehen. Puh - geschafft.


Der Code
Als Referenz noch mal der Sourcecode, den wir im Verlauf des Tutorials erstellt haben:

Delphi-Quellcode:

unit Form1;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, AdDraws, AdClasses, AdTypes;

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

var
  Form1: TForm1;

implementation

{$R *.dfm}

procedure TForm1.FormCreate(Sender: TObject);
begin
  AdDraw := TAdDraw.Create(self);
  AdDraw.DllName := 'AndorraDX93D.dll';
  if AdDraw.Initialize then
  begin
    Application.OnIdle := Idle;
  end
  else
  begin
    ShowMessage('Error while initializing Andorra 2D. Try to use another display'+
                'mode or another video adapter.');
    halt;
  end;
end;

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

procedure TForm1.Idle(Sender: TObject; var Done: boolean);
begin
  if AdDraw.CanDraw then
  begin
    AdDraw.ClearSurface(clBlack);

    AdDraw.BeginScene;
    //Your code here
    AdDraw.EndScene;
    
    AdDraw.Flip;
  end;
  Done := false;
end;

end.

Fazit
Der erste Schritt in Richtung 2D via 3D-Beschleunigung wäre getan. Doch sein wir mal ehrlich, für ein schwarzes Fenster brauchen wir kein Andorra 2D. Darum lernen Sie im nächsten Tutorial:

• Wie Sie ein Bild zeichnen
• Wie Sie das Bild in gleichbleibender Geschwindigkeit über den Bildschirm bewegen
• Und wie Sie den Vollbildmodus verwenden

Dieses Tutorial ist nun ziemlich lang geworden, was daran liegt, dass ich auf alles bis ins Detail eingegangen bin. In den nächsten Tutorialen werde ich die Maßstäbe (besonders in Sachen Delphi) ein wenig höher schrauben und dann geht's auch flotter.

Copyright und Lizenz
(c) by Andreas Stöckel Januar 2007

Revision 2: Oktober 2007
Revision 3: Dezember 2007

Der Inhalt dieses Tutorials steht unter der GNU Lizenz für freie Dokumentation.

[edit=Jelly]AufWunsch von Andreas (Igel457) neue Version hier eingefügt. Mfg, Jelly[/edit]
[edit=Matze]Tutorial aktualisiert (27.12.07). MfG, Matze[/edit]

[igel457]

Die DLLs befinden sich im Ordner "bin" des Andorra Paketes.

[CJ_lux]

hmm, also ich habe jetzt alle dll's die mit 'Andorra' anfangen in den order der mein projekt beinhaltet kopiert.

dann, beim programmstart kommt die meldung, dass diee Dll 'd3dx9_33.dll' fehlt, danach die schon vorher genante meldung..

hab mir jetzt die 'd3dx9_33.dll' im internet einzel herunter geladen und sie dem orddner beigefügt...

Jetzt schein alles zu klappen

Danke für eure Hilfe!

[igel457]

Daran, dass die d3dx9_33.dll fehlt, sieht man, dass du keine aktuelle Version von DirectX, die du von Microsoft bekommst, installiert hast

[CJ_lux]

hehe...


ehm beim starten meines Programms wird immer eine 'adlog.txt'-Datei von andorra erstellt, wie kann ich das verhindern?

mfg
CJ

[igel457]

Die Zeile...
AdDraw.Log.AutoSave := false; ..sollte da seinen Dienst tun.

[CJ_lux]

danke, jetzt noch ein letztes Problem, ich habe die benötigte dlls und meine Texturen als Resource eingebunden
bei OnCreate werden die Resourcen wieder extrahiert

jetzt wenn ich die anwendung starte bekomme ich eine fehler meldung dass die dlls fehlen..
dadurch bricht er die anwendung ab bevor er die dlls überhaupt erstellt hat

wie kann ich verhindern dass er checkt op sie vorhanden sind bevor er sie extrahiert hat?

noch einen schönen Abend wünch ich euch

CJ

[oneP]

Hallo,

ich habe auch ein Problem. Hab alles so gemacht wie es oben beschrieben ist, zur Bibliothek hinzugefügt und die dll´s in den selben ordener wie das Projekt hineinkopiert.

Doch anscheinend hat das Programm ein Problem mit dem laden der "Schwarzen Fläche". Bei mir wird nämlich genau das hier angezeigt:

Delphi-Quellcode:

        ShowMessage('Error while initializing Andorra 2D. Try to use another display'+
              'mode or use another video adapter.');

also ich habe verschiedene Auflösungen probiert und eine gute Grafikkarte hab ich auch.

Woran könnte das liegen?

mfg oneP


EDIT: Hat sich geklärt!

[IronRose]

Genau den gleichen Fehler habe ich auch...
Benutze Delphi 2011 XE

[Toni77]

Bei mir gibt er leider auch nur die Fehlermeldung aus anstatt die schwarze Fläche zu zeichnen.
Also wenn jemand eine Lösung anbieten könnte wäre mir sehr geholfen! (:

Danke!