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
- Types of Plugins
- Packaging Plugins
- General Guidelines
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:
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.
- 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
Types of Plugins
At present, Art of Illusion supports the following types of plugins. Future versions may add more
- 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
- 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
- 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
- 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.
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):
The "plugins" file should be a text file whose contents read as follows:
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:
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.
- 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