Developers
Extending the system
Coming soon.
Writing video output modules
Coming soon.
Writing 2D modules
To write a video output module, you extend the VideoInterfaceModule class found in the video package.
An output module is basically a JPanel 800x600 pixels in size which is serialized, sent across the wire, reinflated and displayed in a JFrame. VideoOutputModule itself is a subclass of JPanel. Consequently, you draw directly onto your custom module class.
Enough of this banter, let's take a look at the minimum code you need to write a module:
public class MinimalModule extends VideoInterfaceModule {
public void init() {
}
public void draw(Graphics g) {
}
public void receiveMessage(AudioMessage message) {
}
public void halt() {
}
}
That's your lot. Not that it will do very much, mind.
init() is called once when your module is received by the video processor. Any operations that may affect the local environment and/or prevent serialization (opening windows and so on) should be placed here and not in a constructor.
draw(Graphics g) can be treated just like paint(Graphics g). If a module is paused, calls to this method should not change what's being drawn on screen. See the discussion of fields later on to find out when your module has been paused.
halt() is called when your module is shut down. You should close any open resources, etc, in this method.
receiveMessage(AudioMessage message) is called when the video processor receives data from the audio processor. Methods of interest on the AudioMessage object are the following:
Most of the information is taken straight from the MIDI data and can be treated as such. There are a few subtle differences though.
getAction() returns a string such as 'Note on' or 'Note off'. Auditorium actually sends 'Note off' messages, rather than a second 'Note on' with a velocity of zero like a lot of MIDI equipment does.
getName() returns the name of the interface sending the data. This is initially set as the default name for that MIDI instrument and will vary greatly between hardware. To simplify writing modules that expect certain instruments, the name of a channel can be overridden by the user by clicking on the icon representing the interface and changing it's name in the left hand option panel.
getTime() returns a long primitive that represents the time the message was received by the audio processor. It gets the time from the Java3D J3DTimer class and consequently is almost ludicrously accurate. If you are not running the video and audio processors on the same computer you may have to compensate for clock drift between the two machines.
You are free to do whatever you want with the data handed to you by the system. Go crazy.
A number of fields in the VideoOutputModule class can be overridden in your constructor or otherwise interacted with. The tree of inheritance looks like this:
debug will use System.out.println() to echo the musical data being received.
info will print the module name and version number to the screen.
name is the name of your module, unsurprisingly.
paused cannot be overridden, but you should test for it every animation loop.
stats will print out a rough estimate of how many times the draw(Graphics g) method is being called - a sort of mock frames per second.
textColor is a awt.Color object that defines what colour the stats and info are printed in.
version is a String representation of your module's version number.
Writing 3D modules
The process of writing a 3D module is very similar to a 2D one. If you wish, you can either extend the convenience class VideoOutputModule3D. This will provide you with a Canvas3D object to draw on and a SimpleUniverse object to create your scene graph. It also allows you to draw 3D axis of any length to make spatial debugging easier, and to navigate around your scene by using the keyboard.
Alternatively you can start with by extending VideoOutputModule and roll your own 3D environment. It's up to you.
The VideoInterfaceModule3D class tree looks like this:
Deploying your module
This is the easy bit. Edit the ModuleSerializer class in the util package and add your module to the Vector object that starts on line 28. Make sure that ModuleSerializer compiles.
Then either run the genmod script from source directory or call the class directly with the following command line argument:
java util.ModuleSerializer
It should print out some messages to the effect that it is deleting old modules and creating new ones. If there are any errors here or if any windows open, you will need to move the offending lines of code from your constructor to the init() method.
Once the script finishes running, your modules are good to go. Fire up the audio and video processors and see your work in action.
Writing instruments
Coming soon.