The Murl Engine supports a number of add-ons, which can be used optionally. Currently the following add-ons are available:

Before we take a closer look, here are the required steps how to use an add-on briefly summarized:

Add header file and library file to the project.
Create an add-on object and register it.
Deregister and release the created add-on object when finished.

Dependencies

Some add-ons are not available on every platform. For example, the Filepanel addon is only available for Windows and OS X but not for iOS or Android.

Additionally some add-ons have dependencies among each other. For example, the Lua add-on may make use of the Filepanel add-on.

The following diagram shows the platform support for each add-on with green arrows and the dependencies among each other with red arrows.

Add-ons platform support & dependencies

To keep the add-on handling simple, each add-on provides at least a so called "null add-on" for every platform. The null add-on is a minimal implementation of the interface without functionality. If the add-on is supported on a given platform, a fully implemented add-on exists on this platform additionally.

Example Filepanel add-on:

Android: libmurl_addons_filepanel_null.a
iOS: libmurl_addons_filepanel_null.a
OS X: libmurl_addons_filepanel_null.a and libmurl_addons_filepanel.a
Windows: murl_addons_filepanel.lib and murl_addons_filepanel_null.lib

Project Configuration

To be able to use an add-on, we have to add the header and library files to our project at first.

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

Note

The Murl Engine provides also the source code of the add-ons:

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

The easiest way to add the add-on files to the different project files is by using the Dashboard and the command Project / Configure Project:

Dashboard Configure Project

The command changes the project settings for all platform specific project files according to the selected options and automatically takes care of dependencies and platform support. Therefore always the right library (add-on or null add-on) is added to the project.

If someone does not want to use the dashboard or is using a not supported IDE/toolchain, the correct libraries need to be added manually to the project files.

Create & Register Add-on

All add-ons share the same namespace Murl::Addons and each add-on has its own specific factory class (e.g. Addons::Filepanel::Factory).

The CreateAddon() method of the factory class can be used to create an add-on object. The method returns an IAddonPtr pointer to the created object and we typically store the pointer in a member variable.

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

The created add-on object also have to be destroyed (released) with the DestroyAddon() method of the factory class.

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

In addition, we have to register the add-on object in our framework to allow the add-on object to work together with our framework (frame update, logic update, etc.). The IApp interface provides the RegisterCustomAddonClasses() method for this purpose. The UnregisterCustomAddonClasses() method can be used to unregister the add-on later on.

Basically we have to implement the two new methods beside the already known methods Configure, Init und DeInit and use it to create and register the add-on objects and to deregister and destroy the add-on objects, respectively.

Example with two add-ons

Declaration of methods and member variables.

    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;
    };

Creation and registration.

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;
}

Deregistration and release.

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;
}