Irrlicht-Tutorial

[malu]

Irrlicht-Tutorial
by malu


Vorwort

Da mich ein gewisser Herr Ineluki darum bat, ein Tutorial für die Irrlicht-Engine zu schreiben und ich mich schon ein bisschen mit der Irrlicht Engine befasst habe, habe ich diesen Auftrag auch gleich angenommen.
Allerdings sei gesagt, dass ich in diesem Tutorial nur 2D-Funktionen von Irrlicht benutzen werde. Da ich außerdem (leider) noch nicht so erfahren mit Linux bin kann ich nicht testen ob der Code auch auf Linux und MacOS läuft. Ebenfalls zu sagen ist, dass dies das erste Tutorial ist das ich je geschrieben hab. Aber lange Rede, kurzer Sinn: Lasst uns anfangen!

Über Irrlicht
Dies ist zum Teil nur eine Übersetzung des englischen FAQ von http://irrlicht.sourceforge.net/.

Was ist Irrlicht?
Irrlicht ist einer High-Performance Open-Source und plattformübergreifende 3D-Engine zur
Erstellung von Echtzeit-3D-Anwendungen.

Woher bekomme ich Irrlicht?
Den Sourcecode, die kompilierten Binärdateien, die Dokumentation und viel anderes Zeug was für die Irrlicht-Engine nützlich sein könnte sowie Links zu Irrlicht-Foren gibt es auf http://irrlicht.sourceforge.net/.

In welcher Programmiersprache wurde Irrlicht entwickelt?
Irrlicht wurde mit C++ entwickelt.

Auf welchen Betriebssystemen läuft Irrlicht?
Irrlicht läuft auf Microsoft Windows ab 98, Linux und Apple Mac OS.
Mehrere Betriebssysteme sind in Planung, werden aber bis jetzt noch nicht offiziell unterstützt.

Welche Grafik-API benutzt Irrlicht?
Irrlicht benutzt OpenGL 1.5, DirectX 8.1, DirectX 9.0, den Irrlicht Software Renderer, den
Apfelbaum Software Renderer oder ein „Null Device“.
Die Wahl bleibt bei dem Programmierer.

Für welche Programmiersprachen gibt es Ports?
Es gibt Ports für Java, Pure Basic, BCX, Blitz Max und Blitz Basic, Lua, Ruby, Python sowie für
den GameMaker.
Die Links gibt es auf der Homepage unter der Kategorie „Links“.

Ok, genug der Rede, auf geht's!


Die Reise in die Welt der Irrlichter beginnt...
So, jetzt geht es endlich los!

Zu erst ein mal müsst ihr eure IDE (ich schätze mal ihrbenutzt eine) auf Irrlicht vorbereiten. Ich werde es an Hand der IDEs Dev-Cpp und CodeBlocks erklären.

Dev-Cpp:
Also, beginnen wir mit Dev-Cpp.
Ihr könntet das jetzt natürlich über den Paketmanager regeln und einfach das Irrlicht-Paket herunterladen, da ich aber wenig von solchen Paketen halte und es sowieso nicht sehr schwer ist, das von Hand einzustellen, werden wir das tun. Zuerst einmal ladet ihr euch von http://irrlicht.sourceforge.net/downloads.html die aktuellste Version des Irrlicht-SDKs herunter und entpackt es beispielsweise in den Ordner C:\Irrlicht\. Nun startet ihr Dev-Cpp, wählt im Menü „Werkzeuge“ den Punkt „Compiler Optionen“. Im sich darauf öffnenden Fenster wählt ihr den Tab „Verzeichnisse“ und darunter den Tab „Bibliotheken“. Im Textfeld tippt ihr nun „C:\Irrlicht\irrlicht-1.1\lib\Win32-gcc“ ein und klickt auf „Hinzufügen“. Jetzt wählt ihr den Tab „C++-Includes“ und tippt dort „C:\Irrlicht\irrlicht-1.1\include“ ein und klickt wieder auf „Hinzufügen“. Nun klickt ihr auf „Ok“. Glückwunsch, ihr hab Dev-Cpp jetzt Irrlicht-tauglich gemacht!

CodeBlocks:
Zuerst einmal müssen wir uns alle benötigten Irrlicht-Dateien von http://irrlicht.sourceforge.net/downloads.html herunterladen. Nehmt die aktuellste Version. Das Archiv entpacken wir dann in das Verzeichnis „C:\Irrlicht“.


Diese Fehlermeldung oder so ähnlich werdet ihr wahrscheinlich bekommen sobald ihr versucht ein Irrlicht-Projekt mit CodeBlocks zu erstellen. Wie ihr also vielleicht gelesen habt müssen wir eine „Custom Variable“ verändern. Dies geht einfach indem ihr auf das „Project“-Menü öffnet, dort „Build options“ auswählt. In dem sich öffnenden Fenster wählt ihr nun den Tab „Custom variables“. Dort werdet ihr dann wahrscheinlich den Eintrag „IRR_BASE“ sehen und dahinter „C:\Irrlicht“. Diesen Eintrag müsst ihr nun auswählen und dann auf den Button „Edit“ klicken. In das Textfeld tippt ihr nun „C:\Irrlicht\irrlicht-1.1“ ein und klickt auf „Ok“. Jetzt klickt ihr wieder auf „Ok“ und seid einfach glücklich, denn ihr habt CodeBlocks nun Irrlicht-tauglich gemacht. Glückwunsch!

Anmerkung: Da es bei einigen Leuten Probleme gab, müsst ihr noch bei den Linkeroptionen eurer IDE mit -lIrrlicht linken.
Anmerkung 2: Unter Linux muss man außerdem mit -lGL und -GLU linken. ( thx Ineluki )

Das eigentliche Tutorial

So, das war genug als Einführung. Nun fängt das eigentliche Irrlicht-Tutorial an. Ich werde nun immer ein bisschen Code schreiben und ihn dann im Nachhinein erklären.

Ein erstes Fenster

Code:

#include <irrlicht.h>
#include <iostream>

using namespace irr; // erspart viel Tipparbeit

int main(int argc, char **argv)
{
    video::E_DRIVER_TYPE driverType;
    std::cout << "Bitte wähle die API die du nutzen möchtest:\n"
                   << " ( a ) DirectX 9.0c\n"
                   << " ( b ) DirectX 8.1\n"
                   << " ( c ) OpenGL 1.5\n"
                   << " ( d ) Software Renderer\n"
                   << " ( e ) Apfelbaum Software Renderer\n"
                   << " ( f ) Null Device\n"
                   << " ( andere ) Schliessen\n";
   
    char i;
    std::cin >> i; // welche API möchte der Benutzer benutzen?
    switch(i)
    {
        case 'a': driverType = video::EDT_DIRECT3D9; break;
        case 'b': driverType = video::EDT_DIRECT3D8; break;
        case 'c': driverType = video::EDT_OPENGL;       break;
        case 'd': driverType = video::EDT_SOFTWARE; break;
        case 'e': driverType = video::EDT_SOFTWARE2;break;
        case 'f': driverType = video::EDT_NULL;             break;
        default: return 0;
    }


    // nun erstellen wir uns ein Fenster
    IrrlichtDevice *device = createDevice(driverType, core::dimension2d<s32>(512, 384));


    if(!device)
    {
        return 1;
    }
    device->setWindowCaption(L"malus Irrlicht Tutorial");
        // Ja, das 'L' ist gewollt :)
    video::IVideoDriver* driver = device->getVideoDriver();
    while(device->run() && driver)
    {
        driver->beginScene(true, false, video::SColor(0, 207, 235, 154));
        driver->endScene();
    }
    device->drop();
    return 0;
 }

So, das ist der Code, den ihr benötigt, um ein Fenster zu öffnen, das einen hellgrünen Hintergrund hat. Jetzt gibt es die Erklärung( die eigendlich unnötig ist, da der Code sehr selbsterklärend ist) .
In Zeile 1 haben wir die Irrlicht-Header-Datei inkludiert, um auf alle Funktionen von Irrlicht zugreifen zu können.
In Zeile 2 haben wir dann die IOStream-Datei inkludiert um die cout- und cin-Objekte nutzen zu können.
In Zeile 4 haben wir den irr-Namespace als Standard-Namespace definiert was uns viel Tipparbeit erspart.
In Zeile 6 geht es dann mit der main-Funktion richtig los.
In Zeile 8 wird dann eine Variable deklariert, in der wird die API speichern die der Benutzer nutzen möchte.
In den Zeilen 9 bis 16 wird dann ein bisschen Text ausgegeben.
In Zeile 18 deklarieren wir wieder eine Variable, diesmal jedoch um die Eingabe des Benutzers aufzunehmen.
In Zeile 19 muss der Benutzer dann einen oder mehrere Buchstaben eintippen um seine API zu wählen.
In den Zeilen 20 bis 29 wird die Eingabe abgefragt und der Variable "driverType" der richtige Wert zugeordnet.
In Zeile 32 erstellen wir ein Fenster mit einer Größe von 512 x 384 Pixeln.
In Zeile 38 geben wir dem Fenster den Namen "malu's Irrlicht Tutorial" (Ja, mir ist kein besserer Name eingefallen; und ja, das "L" ist, wie gesagt, gewollt) .
In Zeile 40 rufen wir die Funktion "getVideoDriver" auf, die uns 2D- und 3D-Geometrie ermöglicht.
In den Zeilen 41 bis 45 haben wir unsere Main-Loop, wo in Zeile 43 das Fenster mit einem hellgrünen Hintergrund gefüll wird und in Zeile 44 wird der Backbuffer mit dem Frontbuffer getauscht.
In Zeile 46 wird dann das Fenster geschlossen und in Zeile 47 wird das Programm beendet.


Damit ist das erste Coding-Kapitel überstanden. Glückwunsch! Jetzt gibt es noch, wie nach jedem Kapitel, eine Funktions- und Variablenübersicht.


Die Variablen:

Code:

irr::video::E_DRIVER_TYPE

Dies ist ein "enum" welches die zu benutzende API speichert.

Code:

irr::IrrlichtDevice

Die ist das Irrlicht-Device. Ohne dieses ist ein korrektes der Engine kaum möglich.

Code:

irr::video::IVideoDriver

Dies ist eins der wichtiugsten Interfaces der Engine. Mit ihm können alle 2D und 3D-Funktionen aufgerufen werden.

Die Funktionen:

Code:

IrrlichtDevice* irr::CreateDevice(    video::E_DRIVER_TYPE deviceType,
                    const core::dimension2d<s32> &windowSize,
                    u32 bits,
                    bool fullscreen,
                    bool stencilbuffer,
                    bool vsync,
                    IEventReceiver *receiver)

Initialisiert ein Zeiger auf ein Objekt vom Typ IrrlichtDevice.

deviceType gibt die zu benutzende API an. Mögliche Werte sind EDT_NULL, EDT_SOFTWARE, EDT_SOFTWARE2, EDT_OPENGL, EDT_DIRECT3D8 und EDT_DIRECT3D9. Standardwert: EDT_SOFTWARE
windowSize gibt die Größe des Fensters oder die Auflösung im Vollbildmodus an. Standardwert: core::dimension2d<s32>(640, 480)
bits gibt die Farbtiefe im Vollbildmodus an. Im Fenstermodus wird dieser Parameter ignoriert und es wird mit der Desktop-Farbtiefe gearbeitet. Standardwert: 16
fullscreen ist truewenn die Anwendung im Vollbildmodus ausgeführt werden soll. Standardwert: false
stencilbuffer ist true wenn ein Stencilbuffer benutzt werden soll. Sollte die API keine Stencilbuffer unterstützen wird keiner verwendet. Stardardwert: false
vsync bestimmt ob vertikale Synchronisation angeschaltet ist. Standardwert: false
receiver kann ein selbsterstellter Eventreceiver sein. Standardwert: 0

Code:

void irr::IrrlichtDevice::setWindowCaption( const wchar_t *text)

Setzt den Fenstertitel.

text gibt den neuen Fenstertitel an.

Code:

irr::video::IVideoDriver irr::IrrlichtDecice::getVideoDriver()

Initialisiert einen Zeiger auf ein Objekt des Typs IVideoDriver.

Code:

bool irr::IrrlichtDevice::run()

Führt das Device aus. Wenn das Device beendet werden möchte gibt die Funktion false zurück.

Code:

bool irr::video::IVideoDriver::beginScene(    bool backBuffer,
                          bool zBuffer
                          SColor color)

Zeichenfunktionen dürfen erst aufgerufen werden, nachdem diese Funktion aufgerufen wurde.

backBuffer gibt an, ob der Backbuffer geleert werden soll. Wenn true, dann wird der Backbuffer mit der im 3. Parameter angegebenen Farbe gefüllt.
zBuffer gibt an, ob der Z-Buffer geleert werden soll. Wenn ja, muss er auf true gesetz werden. Dies ist nicht nötig, wenn man keine 3D-Funktionen benutzt.
Gibt false zurück wenn ein Fehler aufgetreten ist.

Code:

void irr::video::IVideoDriver::endScene()

Der Backbuffer wird auf den Frontbuffer überblendet.

Code:

void irr::IrrlichtDevice::drop()

Schließt Irrlicht.


Die ersten Pixel und Formen:

Code:

#include <irrlicht.h>
#include <iostream>

using namespace irr; // erspart viel Tipparbeit

int main(int argc, char **argv)
{
    video::E_DRIVER_TYPE driverType;
    std::cout << "Bitte wähle die API die du nutzen möchtest:\n"
                   << " ( a ) DirectX 9.0c\n"
                   << " ( b ) DirectX 8.1\n"
                   << " ( c ) OpenGL 1.5\n"
                   << " ( d ) Software Renderer\n"
                   << " ( e ) Apfelbaum Software Renderer\n"
                   << " ( f ) Null Device\n"
                   << " ( andere ) Schliessen\n";

    char i;
    std::cin >> i; // welche API möchte der Benutzer benutzen?
    switch(i)
    {
        case 'a': driverType = video::EDT_DIRECT3D9; break;
        case 'b': driverType = video::EDT_DIRECT3D8; break;
        case 'c': driverType = video::EDT_OPENGL;       break;
        case 'd': driverType = video::EDT_SOFTWARE; break;
        case 'e': driverType = video::EDT_SOFTWARE2;break;
        case 'f': driverType = video::EDT_NULL;             break;
        default: return 0;
    }


    // nun erstellen wir uns ein Fenster
    IrrlichtDevice *device = createDevice(driverType, core::dimension2d<s32>(512, 384));


    if(!device)
    {
        return 1;
    }
    video::IVideoDriver* driver = device->getVideoDriver();
    while(device->run() && driver)
    {
        device->setWindowCaption(L"malus Irrlicht Tutorial");
        driver->beginScene(true, false, video::SColor(0, 207, 235, 154));
        driver->draw2DLine(core::position2d<s32>(1, 1), core::position2d<s32>(510, 382),
                video::SColor(0, 0, 0, 0));
        driver->draw2DPolygon(core::position2d<s32>(470, 40), 30.4f, video::SColor(0, 255, 0, 0),
                10);
        driver->draw2DRectangle(core::rect<s32>(1, 300, 96, 348), video::SColor(0, 255, 0, 0),
                video::SColor(255, 0, 0, 0), video::SColor(255, 0, 0, 0), video::SColor(0, 255, 0, 0));
        driver->endScene();
    }
    device->drop();
    return 0;
}

Die Erklärung des Codes werde ich mir hier sparen, da nicht viel neues hinzugekommen ist und das was neu ist, sehr selbsterklärend ist.

Die Funktionen:

Code:

void irr::video::IVideoDriver::draw2DLine( const core::position2d<s32> &start,
                        const core::position2d<s32> &end,
                        video::SColor color)

Malt eine zweidimensionale Linie.

start gibt den Startpunkt der Linie an.
end gibt den Endpukt der Linie an.
color gibt die Farbe der Linie an. Standardwert: video::SColor(255, 255, 255, 255)

Code:

void irr::video::IVideoDriver::draw2DPolygon(    core::position2d<s32> &center,
                            f32 radius,
                            video::SColor color,
                            s32 vertexCount)

Malt ein zweidimensionales Polygon.

center gibt den Mittelpunkt des Polygons an.
radius gibt den Radius des Polygons an.
color gibt die Farbe des Polygons an. Standardwert: SColor(100, 255, 255, 255)
vertexCount gibt die Anzahl der Eckpunkte an. Standardwert: 10

Code:

void irr::video::IVideoDriver::draw2DRectangle( const core::rect<s32> &pos,
                            SColor colorLeftUp,  
                            SColor colorRightUp,
                            SColor colorLeftDown,
                            SColor colorRightDown,
                            const core::rect< s32 > *clip)

Malt ein Rechteck.


pos gibt die obere-linke Ecke und die untere-rechte Ecke an.
colorLeftUp gibt die Farbe der oberen-linken Ecke an.
colorRightUp gibt die Farbe der oberen-rechten Ecke an.
colorLeftDown gibt die Farbe der unteren-linken Ecke an.
colorRightDown gibt die Farbe der unteren-rechten Ecke an.
clip ist ein Zeiger auf ein Objekt vom Typ core::rect gegen das das Rechteck geclippt werden soll. Standardwert: 0


Hinweis: Von dieser Funktion gibt es eine einfachere Variante:

Code:

void irr::video::IVideoDriver::draw2DRectangle(    const core::rect<s32> &pos,
                            video::SColor color,
                            const core::rect<s32> *clip)

Die Parameter sollten in diesem Fall selbsterklärend sein.

Nachwort

So, das war es erstmal. Ihr könnt mir gerne Wünsche, Lob, Kritik usw. per PN, Mail(mail.for.malu@web.de), ICQ, MSN zukommen lassen oder sie einfach posten. Das nächte Kapitel wird sich mit dem Laden von Bilder beschäftigen. Wenn das Kapitel allerdings niemandem gefällt werde ich aufhören, da ich meine ( leider begrenzte) Zeit ja nicht verschwenden möchte.

~malu~

[Drakes]

Find ich gut, bin gerade mit Dev-C++ am ausprobieren, aber es klappt irgendwie nicht, es gibt 1 Fehlermeldung aus:
[Linker error] undefined reference to `_imp___ZN3irr12createDeviceENS_5video13E_DRIVER_TYPEERKNS_4core11dimension2dIiEEjbbbPNS_14IEventReceiverEPKc'
kA warum dieser Fehler bei mir ausgegeben wird, aber sonst find den Toturial sehr toll, werde die Engine wahrscheinlich ziemlich durch testen ich hoffe, ich kann mich auf weitere Kapitel freuen.

Edit: könnte daran liegen, dass ich zur zeit auch probleme hab, beim initalisieren von Direct X bei Spielen die ich selber gecodet hab
Edit2: andere Beispiel Programme die zur Engine dazu sind, funktiunieren, jetzt bin ich echt Ahnungslos

[Mog]

Edit: könnte daran liegen, dass ich zur zeit auch probleme hab, beim initalisieren von Direct X bei Spielen die ich selber gecodet hab
Edit2: andere Beispiel Programme die zur Engine dazu sind, funktiunieren, jetzt bin ich echt Ahnungslos

...

oGL != directX; die Fehler muessen also wohl unabhaengig sein.

Geh am besten diese Liste durch; wenn du alles richtig machst wird wahrscheinlich alles glatt laufen.
http://irrlicht.sourceforge.net/tut_devcpp.html

[malu]

Drakes, natürlich darfst du auf neue Kapitel hoffen aber im Moment hab ich sehr wenig Zeit. Und zu dem Fehler: Hast du mein Tutorial benutzt oder die von der Irrlicht-Homepage? In der Fehlermeldung wird ein Imp erwähnt den ich in meinem Tutorial nicht benutze.

~malu~

[Drakes]

Nein lag am DirectX, habs jetzt mal neuinstalliert und die Beispiele die man automatisch dazu downloadet haben auch funktiuniert(am besten mit oGL) jetzt funktiunierts auch wieder mit DirectX, das komische ist, dass das Parallax Mapping und Bump Mapping bei einem der Beispiele bei mir nur bei DirectX 8.1 läuft(auch nicht bei 9.0) liegt wahrscheinlich daran dass die Grafikkarte zu alt ist