Moray Plugin SDK Documentation
 

V2.15

Released for use with Moray V3.5 (Build 9330) on the 19th October 2003

Copyright © 1998-2003 SoftTronics, Lutz + Kretzschmar, Munich, Germany

Visit the Plugins page on our website at
http://www.stmuc.com/moray/meplugin.html

General

Moray supports a variety of interfaces to its inner workings for plugins to use. For example, these interfaces allow a plugin to create stock Moray objects (spheres, cubes, etc), query the objects that are present in the scene, implement totally new primitives etc.

A plugin is a DLL with specific entry points. Moray will check in its Plugins folder and will attempt to load any DLLs it finds there. There is no need to register the DLL in any way. The DLL should be written in C++, there is higher level support for some of the interfaces that are exposed. You can still use the lower-level C interfaces, itís just more work for some of the interfaces. There may also be minor hitches using C with the header files, since I have not run it through a C compiler.

A plugin can make use of or expose any number of interfaces. For example, a DLL can contain an import filter and a plugin object.

The Plugin SDK source provides a number of macros for C and C++ as well as MFC classes for developers to facilitate easier development of a plugin. You do not need to use these macros, but they do ease development by taking away some of the drudgery in setting up an interface.

Warning! The Visual C++ Wizard that comes with this Plugin SDK for creating a plugin project is not quite up-to-date yet.

Each interface is identified by a unique ID (similar to how COM components are identified). These unique IDs identify the interface and are generated by the accompanying tool MKUID.EXE.

Once you have published a DLL containing interfaces, the interface must not change in any later versions (again, similar to COM). You can add a new interface to your DLL with a different ID and publish that, but the old interface must stay as defined. Note that if you change implementation details of the interface, you need not change the ID (bug fixing, optimizing). But as soon as a function or data member in the interface is changed, the ID must change.

Interfaces

Object Interface

This interface allows you to integrate a new object into Moray. You supply information about the object (can it be textured, grouped, etc.), a wireframe and optionally a dialog for inclusion in Morays Modify Tab. This dialog can use Morays spinners and sliders. Support for saving and loading to MDL files is also provided.

Files Interface

You can use this interface to hook into Morays File Selector. All you do is provide an extension list and a default extension and Moray will handle the details (such as the last directory, the Search Path, saving to the registry, etc.). You can then call a GetFilename() function of the interface and Moray will return a filename.

Scene Interface

This interface gives you access to the object hierarchy of the currently loaded scene. You can use this interface to create the stock Moray objects (including any plugin objects), add them to CSGs or Groups, delete them. This interface also gives you access to POV-Ray files as they are written.

Import Interface

This interface is quite simple, it merely adds a menu item to the Import submenu of the Files menu and calls a function when the user clicks on it. Youíll probably use this interface in conjunction with the Scene Interface to create objects.

Export Interface

This interface is exactly like the Import interface, it merely adds a menu item to the Export submenu of the Files menu. Again, you'll probably be using this interface in conjunction with the scene interface to query the scene and write out objects.

Menu Interface

This interface allows you to add menu items to Morays main menus as well as creating new submenu. The PluginObj sample plugin demonstrates the use of this interface.

Controller InterfaceNEW!

This interface allows you to manipulate plugin objects in the views.

External Interface

This interface allows you to add interfaces that you can make available to other plugins, either privately or publicly (by releasing the header file and documentation).

Sample Source Code

The Plugin SDK comes with an VC++ 5.0 Workspace containing four sample plugin projects. Except for the PluginObj plugin, the plugins are real-world plugins and were released with Moray V3.3 (Build 7015).

Sample

The Sample plugin is an experimental sample plugin that exercises all interfaces except the Object interface and uses a large chunk of the functionality the SDK offers, but they don't really make more sense than to demonstrate a point. This plugin may not be released to the public, it is merely meant to study how things work in the SDK.

It also exercises the Layers, and the wireframe retrieval system.

SDK Files

At this point itís probably best to fire up Moray and the compiler and take a look at the sample plugin code. Load the PluginSDK workspace and browse through the four projects.

The following is a list of files in the base directory for the plugins that are provided. The source code is well-documented and should be pretty understandable. But since I have been looking at the code for quite a long time, some stuff may be confusing or unclear. In this case, please let me know, so that I can adapt either the code or the documentation.

Plugin.h contains the low-level interface definition of the plugin architecture. It defines return values and data structs as well as the actual function blocks (interfaces). This file is also included by Moray, so it defines all required aspects of the plugin interface.
PluginObj.hpp contains the base class definition that C++ objects can use.
PluginObj.cpp contains the class implementation.
PluginHelpers.hpp contains macros to provide high-level support for the interfaces.
PluginDebug.cpp contains some debugging and logging functions for your convenience.
MFCPluginApp.h contains the CWinApp-derived base class that MFC-based plugins need to derive their application class from.
MFCPluginApp.cpp implements the CWinApp-derived base class.
MFCPluginDialog.h contains the CDialog-derived base class that MFC-based plugins need to derive their object dialogs (for inclusion in Morays Modify Tab) from.
MFCPluginDialog.cpp implements the CDialog-derived base class.
MFCInterfaces.hpp provides C++ class to the interfaces.
MFCInterfaces.cpp implements the interface classes.
MKUID.EXE is the program that must be used to generate the unique IDs associated with each interface.

Current implementation caveats

There are a number of things that are missing, youíre welcome to give me input on this. These are things that I am thinking of still implementing if they are needed.

Documentation

The documentation for the Plugin SDK functions and data structures can be found here: (local links)

You can navigate freely in the documentation, all the files are interlinked at the top of the page. The documentation is also available online. Check http://www.stmuc.com/moray/meplugin.html.
Please join the Moray SDK mailing list (on Yahoo!Groups) and participate in the discussions there (you should have received instructions in the email that came in reply to your application to download the SDK).

Publishing Plugins

We would like a copy of the public release of any plugins you write to place on our website. It is an advantage to have the plugins in one spot and users will likely look on our Plugins page first.

Also, if you are working on a plugin, we'd love to hear from you (email us) so that we can put up this information on the plugins page of our website.

... and finally....

Please let me know if any other interfaces to Moray or information about the scene is needed for any plugins you would like to develop.

- Lutz
   moraydev@stmuc.com
   19th October 2003