Die Murl Engine unterstützt eine Reihe von Add-ons, die optional verwendet werden können. Derzeit stehen folgende Add-ons zur Verfügung:

Bevor wir uns näher mit Add-ons befassen, hier die notwendigen Schritte für die Verwendung eines Add-ons zusammengefasst:

Header- und Bibliotheks-Datei zum Projekt hinzufügen.
Ein Add-on Objekt erzeugen und im Framework registrieren.
Das Add-on Objekt deregistrieren und freigeben, wenn es nicht mehr benötigt wird.

Abhängigkeiten

Nicht jedes Add-on ist für alle Plattformen verfügbar. Beispielsweise gibt es das Filepanel Add-on nur für Windows und OS X, nicht aber für iOS und Android.

Zusätzlich haben die Add-ons teilweise untereinander Abhängigkeiten. Beispielsweise kann mit dem Lua Add-on auch das Filepanel Add-on genutzt werden.

Die folgende Grafik zeigt für die einzelnen Add-ons die Plattform-Unterstützung mit grünen Pfeilen und die Abhängigkeiten untereinander mit roten Pfeilen an.

Add-ons Plattformsupport & Abhängigkeiten

Um die ganzen Abhängigkeiten möglichst einfach handhaben zu können, gibt es für jedes Add-on und jede Plattform zumindest ein Null-Add-on, welches das Interface implementiert, aber lediglich eine Leerimplementierungen beinhaltet. Wird ein Add-on auf einer Plattform nicht unterstützt, gibt es für diese Plattform nur das Null-Add-on, ansonsten gibt es zusätzlich zum Null-Add-on auch das voll implementierte Add-on.

Beispiel Filepanel Add-on:

Android: libmurl_addons_Filepanel_null.a
iOS: libmurl_addons_Filepanel_null.a
OS X: libmurl_addons_Filepanel.a und libmurl_addons_Filepanel_null.a
Windows: murl_addons_Filepanel.lib und murl_addons_Filepanel_null.lib

Projekt Konfiguration

Um ein Add-on verwenden zu können, müssen zunächst die entsprechenden Header- und Bibliotheks-Dateien dem Projekt hinzugefügt werden.

Header: murl/base/include/addons/{name}/{file_name}.h
Binaries: murl/base/binaries/{os/studio/config}/{file_name}.{a|lib}

Zu beachten

Hinweis: Die Murl Engine liefert auch den Source-Code für die Add-ons mit aus:

Source-Code: murl/base/source/addons/{name/os}/{file_name}.{cpp|h}

Das Hinzufügen der Add-on Dateien zu den verschiedenen Projekten geht am einfachsten mit dem Dashboard und dem Befehl Project / Configure Project:

Dashboard Configure Project

Dabei ändert das Dashboard die Projekteinstellungen für alle Plattformen passend zu den gewählten Optionen und berücksichtigt dabei automatisch Abhängigkeiten sowie Plattformsupport und bindet daher immer die richtigen Dateien (Add-on oder Null-Add-on) ein.

Wer das Dashboard nicht verwenden möchte oder eine andere IDE/Toolchain verwendet, kann die passenden Bibliotheken natürlich auch selbst seinem Projekt hinzufügen.

Add-on Erzeugen und Registrieren

Alle Add-ons teilen sich den gemeinsamen Namespace Murl::Addons und besitzen eine spezifische Factory-Klasse (z.B. Addons::Filepanel::Factory).

Mit der CreateAddon() Methode der Factory-Klasse können wir ein Add-on Objekt erzeugen und erhalten als Rückgabewerte einen IAddonPtr, den wir in einer Member-Variable speichern können.

mFilepanelAddon = Addons::Filepanel::Factory::CreateAddon();

Das erzeugte Add-on Objekt muss mit der DestroyAddon() Methode der Factory-Klasse auch wieder zerstört (freigegeben) werden, wenn es nicht mehr benötigt wird.

Addons::Filepanel::Factory::DestroyAddon(mFilepanelAddon);

Damit das Add-on Objekt mit dem Framework zusammenarbeiten kann (Frame-Update, Logic-Update, etc.), müssen wir das Add-on Objekt noch im Framework registrieren. Das IApp Interface stellt dafür die Methode RegisterCustomAddonClasses() zur Verfügung. Die Methode UnregisterCustomAddonClasses() kann für die Deregistrierung des Add-ons verwendet werden.

Um Add-ons verwenden zu können, müssen wir also in unserer App-Klasse neben den schon bekannten Methoden Configure, Init und DeInit noch die beiden neuen Methoden implementieren und dort die Add-on Objekte erzeugen und registrieren bzw. deregistrieren und freigeben.

Beispiel mit zwei Add-ons

Deklaration der Methoden und Membervariablen.

    class MyApp : public AppBase
    {
    public:
        MyApp();
        virtual ~MyApp();

        virtual Bool Configure(IEngineConfiguration* engineConfig, IFileInterface* fileInterface);
        virtual Bool Init(const IAppState* appState);
        virtual Bool DeInit(const IAppState* appState);

        virtual Bool RegisterCustomAddonClasses(IAppAddonRegistry* addonRegistry);
        virtual Bool UnregisterCustomAddonClasses(IAppAddonRegistry* addonRegistry);

    protected:
        MyLogic* mLogic;

        Addons::Vuforia::IAddonPtr mVuforiaAddon;
        Addons::Filepanel::IAddonPtr mFilepanelAddon;
    };

Initialisierung und Registrierung.

Bool App::MyApp::RegisterCustomAddonClasses(IAppAddonRegistry* addonRegistry)
{
    mFilepanelAddon = Addons::Filepanel::Factory::CreateAddon();
    if (!addonRegistry->RegisterAddon(mFilepanelAddon))
    {
        return false;
    }

    mVuforiaAddon = Addons::Vuforia::Factory::CreateAddon();
    if (!addonRegistry->RegisterAddon(mVuforiaAddon))
    {
        return false;
    }
    return true;
}

Deregistrierung und Freigabe.

Bool App::MyApp::UnregisterCustomAddonClasses(IAppAddonRegistry* addonRegistry)
{
    if (!addonRegistry->UnregisterAddon(mFilepanelAddon))
    {
        return false;
    }
    Addons::Filepanel::Factory::DestroyAddon(mFilepanelAddon);

    if (!addonRegistry->UnregisterAddon(mVuforiaAddon))
    {
        return false;
    }
    Addons::Vuforia::Factory::DestroyAddon(mVuforiaAddon);
    return true;
}