Art of Illusion



To Documentation Index


Author: Peter Eastman
Last Modified: Mar. 5, 2004
Modified For: v1.7
Original Release Date: Oct. 4, 2000
Originally Written For: v0.6

Contents

  1. Overview
  2. Types of Plugins
  3. Packaging Plugins
  4. General Guidelines

Overview

 The Art of Illusion plugin API allows you to write new modules which extend the functionality of Art of Illusion in a variety of ways. Plugins typically:
  • Add new features which are not part of the core program
  • Are written in Java
  • May contain any number of Java classes, data files, and other resources
  • Are packaged as a single jar file
  • Are installed simply by placing the jar file in the "Plugins" folder
This tutorial describes the various types of plugins which can be written, and general information on how to write and package them that is common to all plugin types. It does not give detailed information on how to write any particular type of plugin. It is intended that there will be additional tutorials which describe the details of how to write each plugin type.

Types of Plugins

 At present, Art of Illusion supports the following types of plugins. Future versions may add more types.
  • Renderers create images of scenes. Art of Illusion is distributed with two renderers (the Raytracer and the Raster renderer), which are packaged together as a single plugin. Renderers are Java classes which implement the artofillusion.Renderer interface.
  • Modelling Tools provide new capabilities for creating or editing parts of a scene. They are listed in the Tools menu. Modelling Tools are Java classes which implement the artofillusion.ModellingTool interface.
  • Translators allow Art of Illusion to read and write scenes in foreign file formats. Translators are Java classes which implement the artofillusion.Translator interface. At present, Art of Illusion is distributed with Translators for VRML, Wavefront, and POV-Ray files.
  • Textures allow you to define procedural textures which you can use in your scenes. Textures are Java classes which subclass artofillusion.texture.Texture. (In practice, they generally subclass either artofillusion.texture.Texture2D or artofillusion.texture.Texture3D.)
  • Texture Mappings define how a texture is mapped to the surface of an object. Texture mappings are Java classes which subclass artofillusion.texture.TextureMapping. (In practice, new mappings defined by plugins will usually subclass artofillusion.texture.NonlinearMapping2D.)
  • Materials allow you to define procedural materials which you can use in your scenes. Materials are Java classes which subclass artofillusion.material.Material. (In practice, they generally subclass artofillusion.material.Material3D.)
  • Material Mappings define how a material is mapped to the interior of an object. Material mappings are Java classes which subclass artofillusion.material.MaterialMapping.
  • Image Filters define post-rendering effects that can be applied to images. Any number of filters may be attached to a camera, and they may define adjustable parameters so that the effect of the filter can be modified or even animated. Image filters are Java classes which subclass artofillusion.image.filter.ImageFilter.
  • Procedural Modules add new functions to the Procedure editor. They can be used within any procedural element of a scene: textures, materials, animation tracks, etc. Procedural modules are Java classes which subclass artofillusion.procedural.Module.
  • Generic Plugins provide a general purpose mechanism for implementing new features that do not fit easily into any of the above categories. They are Java classes which implement the artofillusion.Plugin interface. This interface defines a single method, processMessage(), which is called when various events take place: the program is started, the program exits, a scene editing window is opened, a scene editing window is closed, a file is saved, etc.

Packaging Plugins

 To package your Java classes as a plugin, place the main plugin class (the one which implements the appropriate interface or extends the appropriate class) and any other classes or files it needs into a single jar file. You may include multiple plugins in a single jar file. In addition, the jar file must contain a text file called "plugins" (all lower case) which acts as an index. This file should simply list the fully qualified class name of each plugin class, one on each line.

Each class file must be stored in the correct directory within the jar file that corresponds to the package it is in. Otherwise, the class loader will not be able to locate it.

To make all of this clearer, suppose that you wish to package two plugins into a jar file, whose fully qualified class names are com.mycompany.GoodPlugin and com.mycompany.BetterPlugin. The jar file should then contain three entries (in addition to any other classes or files which may be used by the plugins): 

com/mycompany/GoodPlugin.class
com/mycompany/BetterPlugin.class
plugins

The "plugins" file should be a text file whose contents read as follows: 

com.mycompany.GoodPlugin
com.mycompany.BetterPlugin

General Guidelines

When you start up Art of Illusion, one of the first things it does is to look through every file in the Plugins directory. For each one, it first determines whether it is a zip or jar file, and if so, looks for an entry called "plugins". It loads that entry, and uses it to identify the main plugin classes for that file. It loads each plugin class, and creates an instance of it by calling newInstance() on the class object. For some plugin types, such as Renderers, only that one instance is ever created, and used repeatedly. For other types, such as Textures, many other instances may be created later.

This procedure has a few consequences which you should keep in mind. First, it means that every plugin class must have a constructor which takes no arguments . This allows it to be instantiated with a call to Class.newInstance().

Second, when many plugins are present, the time required to load and instantiate all of them can be significant. It also means that memory must be used to store every plugin class, even if the user never actually uses that plugin. To alleviate both of these problems, it often is a good idea to minimize the size of the main plugin class. By placing the bulk of the code into helper classes which do not get loaded until the plugin is actually used, you can save memory and reduce the startup time.

Every plugin is loaded by a separate class loader which automatically sets up the classpath to include the following:

  • Everything in the system classpath (i.e. everything in the java.* packages)
  • The classes in ArtOfIllusion.jar (containing the classes in the artofillusion.* packages)
  • Everything in the plugin's own jar file
This means that a plugin can access all of the standard system and application classes, as well as all the other classes in its jar file, but cannot access the classes belonging to other plugins (unless you explicitly load them with your own classloader). Thus, you generally do not need to worry about class name conflicts between unrelated plugins.