GSModeler Engine Version: 9.0

How to Develop a Rendering Add-On to ArchiCAD 9

Introduction

This documentation describes how to create a rendering add-on for ArchiCAD 8.1. The rendering add-on is able to substitute the built-in rendering engine everywhere where ArchiCAD can generate a rendered image. The rendering add-on can not only work in photorendering command, but also in fly-through, sun studies and VR generation.

The Rendering API contains everything that is necessary to create a rendering add-on. It contains libraries, header files, interface library sources and sources of an example rendering add-on.

This document assumes that you are a programmer who is familiar with the C++ language and that you have some experience in GDL programming, especially in using GDL primitive elements. For information about GDL, please refer to the GDL Reference Manual that is part of the ArchiCAD package.

Capabilities of rendering add-ons

The main feature of a rendering add-on is the image generation, of course. The engine has to create the image from the model using the camera and the rendering setting data.

The renderer is able to use extra setting data by creating one or more panel into the rendering settings dialog.

Another feature that the add-on is able to use is extra material and light parameters. This extra parameters can be set in the GDL script material and light definition commands. The add-on can create one or more panel in the material settings dialog, where the user can modify parameters this add-on depends on.

The ArchiCAD add-on manager displays description strings about add-ons. The add-on can write into this description some useful information for the users.

Interfaces

The Rendering API contains two interfaces. The first is a C interface between the add-on and the ArchiCAD. This is a low level interface for ensuring compiler independence. The add-on doesn't have to use this interface directly.

The second interface is a C++ interface which uses the previous C interface. This is a high level interface between the add-on source and the interface library. This is what add-on writers can use in their add-ons.

The low level C interface

The add-on contains one or more interfaces for communication, and an exported function for retrieving them. The funcionality of the add-on depends on the found interfaces. A rendering add-on can contain the following four interfaces:

Rendering interface
This is the main interface in a rendering add-on. It contains the all the functionality that is needed for creating rendered image.
Add-On manager interface
The add-on manager of the ArchiCAD communicates with the add-on via this interface.
Rendering dialog interface
The add-on is able to create one ore more new tab page in the rendering settings dialog of the ArchiCAD. This is an optional interface. If it is missing then the add-on won't have its own rendering parameters in the settings dialog.
Material dialog interface
The add-on is able to create one ore more new tab page in the material settings dialog of the ArchiCAD. This is an optional interface. If it is missing then the add-on won't have its own material parameters in the settings dialog.

The interfaces have a common header followed by an interface dependent part. The header contains information about the interface (type, version, compatibility). The second part contains pointers to interface functions.

The high level C++ interface

The interface library connects to the ArchiCAD via the low level C interface and shows a high level C++ interface towards the add-on. The API contains the source of this library. The developers of add-ons have to make the interface library from this source using the same compiler as they use for compiling add-ons. The add-on and the compiling C++ interface of the library will be compatible using this method.

The interface contains exported classes, functions and required ancestor classes the developer has to use. The required classes are the interface implemented by the add-on. The add-on has to create a new class for each interface, and has to implement the pure virtual methods of this class. The API contains the following seven ancestor classes for the interface classes:

RenderingInterfaceImp
The template ancestor classes of the rendering interface. The rendering interface object contains some common information about the rendering engine and contains the active renderers. The template parameter has to contain the renderer class.
RendererImp
The ancestor class of the renderer. The instances of this class make the rendered image.
AddOnManagerInterfaceImp
The ancestor class of the add-on manager interface.
RenderingDialogInterfaceImp
The ancestor class of the rendering settings dialog interface.
RenderingPanelInterfaceImp
The ancestor class of the rendering settings panel interface.
MaterialDialogInterfaceImp
The ancestor class of the material dialog interface.
MaterialPanelInterfaceImp
The ancestor class of the material panel interface.

Developing Rendering Add-Ons

Making an interface library

The interface library sources can be found in the LibSrc folder of the Rendering API. These source files contain the whole library. The necessary headers can be found in the Inc folder. The make files of the example rendering contain the library creation rules.

Required classes and objects

The addon sources have to contain some required classes and objects and may contain some optional ones. Here is the list of required and optional elements:

  • Interface manager object.
  • Renderer class.
  • Rendering interface class.
  • Rendering interface object.
  • Add-on manager class.
  • Add-on manager object.
  • Rendering dialog class (optional).
  • Rendering dialog object (optional).
  • One or more rendering panel class (optional).
  • One or more rendering panel object (optional).
  • Material dialog class (optional).
  • Material dialog object (optional).
  • One or more material panel class (optional).
  • One or more material panel object (optional).

All rendering add-ons have to contain one interface manager object. The implemented interfaces register themselves into this manager.

static GSModeler::InterfaceManager interfaceManager;

The renderer is the heart of the rendering add-on, this makes the rendered image. The renderer class has to descend from the RendererImp class, and has to implement the inherited MakePicture method.

class Renderer : GSModeler::RendererImp {
private:
    // The implementation members and methods.
public:
    virtual void MakePicture (const GSModeler::Model&              model,
                              const GSModeler::Camera&             camera,
                              const GSModeler::RenderingSettings&  renderingSettings,
                              GSModeler::PixelMap*                 pixelMap,
                              GSModeler::ProcessControl*           processControl);
}

The rendering interface stores the active renderer object inside itself. The rendering interface class has to descend from the RenderingInterfaceImp class. This is a template class, which is requires the renderer class as the template parameter. This class returns some information about the rendering engine (name, features, ...).

class RenderingInterface : GSModeler::RenderingInterfaceImp<Renderer> {
public:
    explicit RenderingInterface (GSModeler::InterfaceManager* manager);         // Constructor.

    virtual void GetName (char* name);                                          // The engine name.
    virtual void GetFeatures (GSModeler::RenderingFeatures* features);          // The implemented features.
    virtual void SetOptions (GSModeler::RenderingSettings* renderingSettings);  // The extra options (optional).
}

The add-on has to contain an instance of the rendering interface class registered into the interface manager.

static RenderingInterface renderingInterface (&interfaceManager);

The add-on manager of the ArchiCAD shows some information about the add-on (name, description). The add-on manager interface in the rendering add-on can communicate with the add-on manager. This class has to descend from the AddOnManagerInterfaceImp class.

class AddOnManagerInterface : AddOnManagerInterfaceImp {
public:
    explicit AddOnManagerInterface (GSModeler::InterfaceManager* manager);  // Constructor.

    virtual void GetName (char* name);                                      // The engine name.
    virtual void GetDescription (char* description);                        // The description string of the engine.
};

The add-on has to contain an instance of the add-on manager interface class registered into the interface manager.

static AddOnManagerInterface addOnManagerInterface (&interfaceManager);

The next elements are optional.

The add-on can customize the rendering settings dialog. The rendering dialog interface can create one or more own panel in the rendering settings dialog. The class of this interface has to descend from the RenderingDialogInterfaceImp class.

class RenderingDialogInterface : RenderingDialogInterfaceImp {
public:
    explicit RenderingDialogInterface (GSModeler::InterfaceManager* manager);  // Constructor.

    virtual void      GetName (char* name);                                               // The name of the rendering engine.
    virtual DG::Icon  GetIcon (char* name);                                               // The icon of the rendering engine.
    virtual void      GetFeatures (RenderingDialogFeatures* features);                    // Information about the rendering dialog.
    virtual void      RenderingSettingsChanged (GSModeler::RenderingSettings* renderingSettings);     // The rendering settings are modified.
};

The add-on has to contain an instance of the rendering dialog interface class registered into the interface manager.

static RenderingDialogInterface renderingDialogInterface (&interfaceManager);

The rendering panel interface can create one panel in the rendering settings dialog. The class of this interface has to descend from the RenderingPanelInterfaceImp class.

class RenderingPanelInterface : RenderingPanelInterfaceImp {
public:
    explicit RenderingPanelInterface (GSModeler::RenderingDialogInterfaceImp* manager);  // Constructor.

    virtual void      GetName (char* name);                                               // The name of the panel.
    virtual DG::Icon  GetIcon (char* name);                                               // The icon of the panel.
    virtual bool      CreateTabPage (const DG::TabControl& tabControl);                   // Creating the panel.
    virtual void      DestroyTabPage (void);                                              // Deleting the panel.
    virtual void      RenderingSettingsChanged (GSModeler::RenderingSettings* renderingSettings);     // The rendering settings are modified.
};

The add-on has to contain an instance of the rendering panel interface class registered into the rendering dialog interface object.

static RenderingPanelInterface renderingPanelInterface (&renderingDialogInterface);

The add-on can use extra material parameters for rendering. This extra parameter can be modified in the material dialog. The material dialog interface can create one or more new tab page in this dialog. The class of this interface has to descend from the MaterialDialogInterfaceImp class.

class MaterialDialogInterface : MaterialDialogInterfaceImp {
private:
    MaterialTabPage*          tabPage;                                               // The created tab page.
    MaterialTabPageObserver*  observer;                                              // The observer of the tab page.

public:
    explicit NewRendMaterialDialogInterface (GSModeler::InterfaceManager* manager);  // Constructor.

    virtual void      GetName (char* name);                                               // The name of the rendering engine.
    virtual DG::Icon  GetIcon (char* name);                                               // The icon of the rendering engine.
    virtual void      MaterialChanged (GSModeler::Material* material);     // The material parameters are modified.
};

The add-on has to contain an instance of the material dialog interface class registered into the interface manager.

static AddOnManagerInterface addOnManagerInterface (&interfaceManager);

The material panel interface can create one panel in the material settings dialog. The class of this interface has to descend from the MaterialPanelInterfaceImp class.

class MaterialPanelInterface : MaterialPanelInterfaceImp {
public:
    explicit MaterialPanelInterface (GSModeler::MaterialDialogInterfaceImp* manager);  // Constructor.

    virtual void      GetName (char* name);                                               // The name of the panel.
    virtual DG::Icon  GetIcon (char* name);                                               // The icon of the panel.
    virtual bool      CreateTabPage (const DG::TabControl& tabControl);                   // Creating the panel.
    virtual void      DestroyTabPage (void);                                              // Deleting the panel.
    virtual void      MaterialChanged (GSModeler::Material* material);     // The material parameters are modified.
};

The add-on has to contain an instance of the material panel interface class registered into the material dialog interface object.

static MaterialPanelInterface MaterialPanelInterface (&materialDialogInterface);

Required resources

Resources can be written using the native resource format (.RC files on Windows and .r files on Macintosh), or the Graphisoft resource format (.GRC files). This format ensures a platform independent way to create resources. The API contains a resource compiler to convert these files to native resource files.

Only one resource is required in the rendering add-on. This is the MDID resource, wich identifies the add-on. ArchiCAD checks the validity of this identifier and the add-on won't be loaded if this check is fails.

The platform independent Graphisoft resource format (.GRC) of this resource:

#if defined (macintosh)
#include "ResTmpl.r"
#endif

'MDID' 32500 "Add-On Identifier" {
    /* Registration ID */
    /* Local ID */
}

The native Windows resource format (.RC) of this resource:

32500 MDID
BEGIN
    8, 0,
    0L + /* Registration ID */,
    0L + /* Local ID */
END

The native Macintosh resource format (.r) of this resource:

resource 'MDID' (32500, "Add-On Identifier", purgeable) {
    /* Registration ID */,
    /* Local ID */
};

Certainly, the resource can contain version resource and string table for the name, description strings and dialog resources (option, material tab page).
Copyright © 2004 - Graphisoft R&D Software Development Rt. All rights reserved worldwide.