Basics

A shared library placed in the Realsoft 3D's plugins folder and containing the following two "C" functions:

    int R3LibraryInit(R3APP *app);
    int R3LibraryFree(R3APP *app);

is loaded when an applications is started.

Any application can load your plugin. Therfore, in the R3LibraryInit() function the plugin should study which sub systems exist in the application that loaded the plugin and then register only the corresponding classes into the application.

For example, if the application does not have an object class for managering geometric objects, then the plugin should not attemp to register geometric objects.

Another example: if your plugin implements new tool button classes, then register them only if the application has tool bar class.

A Minimal Plugin

The following example shows a minimal source code for a plug-in. The initialization function calls R3Info() function just to show the plug-in is really loaded and works.

    #include <oops/r3app.h> 

    int R3LibraryInit(R3APP *app)
    {
        R3Info("My plugin works");
        return TRUE;
    }

    int R3LibraryFree(R3APP *app)
    {
        return TRUE;
    }

In order to compile and link the above source code, you need two additional files: a .DEF file and a makefile. The former is only needed for Windows platforms but you should always write one to make your plugin platform independent.

The purpose of the .DEF file is to export the R3LibraryInit and R3LibraryFree functions so that Realsoft 3D can call them. The structure of the .def file is shown below.

    LIBRARY dummy

    EXPORTS
        R3LibraryInit
        R3LibraryFree

For more information about .DEF files, consult Microsoft Visual Studio documentation.

The structure of makefile is as follows:

    TARGETLIB = dummy

    CFILES = plugin.c

    INCLIBS=

    !include $(V4HOME)/$(V4MKDLL).mak

    # dependencies
    plugin.o: plugin.c

In all real plugins you will also need to define INCLIBS macro to tell which Realsoft 3D libraries should be linked with your plugin. In this case we only depend on Realsoft 3D kernel library. The base makefiles always include this library, so we don't need to define INCLIBS macro for now.

TARGETLIB macro defines the name for the plugin, in platform independent way. On windows the actual name of the built library is dummy.dll and on unix based systems it is libdummy.so. The makefile automatically builds the library into Realsoft 3D's plugins folder.

To build the plugin just enter r3make. Next time you start Realsoft 3D you should see "My Plugin works" message.

You can find the source code for this plug-in from 'samples/plugins/dummy' folder.